63 lines
1.9 KiB
Markdown
63 lines
1.9 KiB
Markdown
# Tool Contracts
|
|
|
|
## Naming
|
|
|
|
```text
|
|
<domain>.<resource>.<action>
|
|
```
|
|
|
|
Examples:
|
|
|
|
```text
|
|
project.status.get
|
|
gitea.repository.list
|
|
gitea.file.read
|
|
knowledge.document.search
|
|
unraid.container.list
|
|
unraid.container.inspect
|
|
unraid.container.logs
|
|
```
|
|
|
|
Names are lowercase ASCII, dot-separated, stable, and globally unique within the Hub. Do not include project names in canonical tool names; project scope comes from the virtual server and identity context.
|
|
|
|
## Required manifest fields
|
|
|
|
- canonical name and semantic version;
|
|
- title and managed description;
|
|
- connector type;
|
|
- input and output JSON Schema;
|
|
- risk class;
|
|
- required capability and scopes;
|
|
- allowed environment classes;
|
|
- timeout, rate, row/item, and byte limits;
|
|
- redaction profile;
|
|
- idempotency and side-effect annotation;
|
|
- lifecycle status and replacement when deprecated.
|
|
|
|
## Inputs
|
|
|
|
- reject unknown fields by default;
|
|
- use enums and bounded strings;
|
|
- use opaque registered references rather than raw paths/URLs;
|
|
- pagination uses bounded `limit` and opaque cursor;
|
|
- environment/project are not accepted when endpoint context already determines them.
|
|
|
|
## Outputs
|
|
|
|
- structured data first;
|
|
- stable machine-readable error code;
|
|
- explicit truncation and cursor;
|
|
- source and generated time metadata;
|
|
- no secrets, raw auth headers, or unbounded logs;
|
|
- validate against the output schema before returning.
|
|
|
|
## Side effects
|
|
|
|
Every v1.0 tool is `readOnly: true`. The v1.1 Gitea exception is an exact R2
|
|
allowlist of six tools: branch, issue, comment, bounded file and pull-request
|
|
creation/update. MCP annotations must truthfully mark them non-read-only and
|
|
the client must confirm the external action. The server independently enforces
|
|
the project binding, R2 policy, separate write credential, safe change-branch
|
|
namespace, input budgets and target allowlist. A tool whose target API might
|
|
mutate through a GET-like endpoint remains prohibited.
|