# Agentkind READ-ONLY MCP server — v1 (Issue #14)

A minimal **read-only** MCP server that exposes the canonical Agentkind registry
to any MCP-capable runtime. stdio first; no hosted service, no dynamic backend.

**Source of truth:** this server contains no verification logic. It imports the
shared read-only core from Issue #19, `core/agentkind_core.py`, and marshals
JSON-RPC around it.

## Canonical discovery flow

Always begin at the discovery root. Never start from a hard-coded contract.

```
/.well-known/agentkind.json      (agentkind_discover)
        |
        +-- api.contracts  ---->  contracts.json      (agentkind_contracts)
        |                              |
        |                              +--> official contract, compared EXACTLY
        |                                   against the candidate (agentkind_verify)
        +-- api.status     ---->  status.json         (agentkind_status)
        +-- api.links      ---->  links.json          (agentkind_links)
        +-- api.risk       ---->  risk.json           (agentkind_risk)
```

## Tools — exactly six, all read-only

| Tool | Input | Returns |
|---|---|---|
| `agentkind_discover` | — | discovery root document |
| `agentkind_status` | — | status document |
| `agentkind_contracts` | — | contracts registry |
| `agentkind_verify` | `address` (required), `chain`?, `network`? | `{ verdict, canonical, detail, ... }` |
| `agentkind_links` | — | official links document |
| `agentkind_risk` | — | risk / non-affiliation document |

`verdict` is one of `"true"`, `"false"`, `"unknown"`.

## Verify semantics

- The official contract is **always resolved from the live canonical registry**.
  It is never hard-coded as an authority in this server.
- Comparison is an **exact, case-sensitive string comparison**. No lowercasing,
  uppercasing, trimming, or autocorrection. Wrong case => `false`.
- `chain` / `network` are **optional** hints:
  - match zero registry entries => `unknown` (never guess);
  - match more than one => `unknown` with an `AMBIGUOUS` detail;
  - omitted and the registry exposes multiple plausible official mainnet
    contracts => `unknown` with an `AMBIGUOUS` detail.
- Any fetch/parse failure => `unknown`. The server never guesses and never
  falls back to stale or cached data.

## Hard boundary

MCP v1 is identity/verification only. Structurally absent and forbidden:

- wallet connection
- signing
- transfer
- buy / sell
- transaction construction
- private keys / secrets
- Moltbook `post_create` or any other community write operation
- production mutation

There is no code path in the server that issues a non-GET request.

## Run it (stdio)

```bash
python3 agentkind_site/skills/agentkind-identity/mcp/agentkind_mcp_server.py
```

Override the registry for a self-hosted / air-gapped mirror:

```bash
AGENTKIND_DISCOVERY_URL=https://mirror.example/.well-known/agentkind.json \
  python3 .../mcp/agentkind_mcp_server.py
```

## Configuration

- `mcp_stdio_config.json` — generic stdio config (replace the relative arg with
  an absolute path for clients that launch from another working directory).
- `examples/hermes_agent_mcp.json` — Hermes Agent native MCP configuration.
- `examples/openclaw_mcp.json` — OpenClaw MCP configuration.

Copy the `mcpServers` block into your client's config and replace
`/ABS/PATH/TO/...` with the real path to `agentkind_mcp_server.py`.

## Client examples

- `examples/python_client.py` — dependency-free JSON-RPC over stdio.
- `examples/typescript_client.ts` — uses `@modelcontextprotocol/sdk`.

## Acceptance

```bash
python3 agentkind_site/tools/mcp_acceptance.py
```

Drives the real server over real stdio and emits:
`MCP_DISCOVERY`, `MCP_STATUS`, `MCP_CONTRACTS`, `VALID_ADDRESS`, `WRONG_CASE`,
`UNRELATED`, `NETWORK_FAILURE`, `WALLET_SIDE_EFFECTS`, `FINAL_STATUS`.