docs: comprehensive update for MCP, ANP, federation, and new adapters

Update all docs to reflect current codebase:
- architecture.md: add MCP Server, ANP Bridge, federation, WebTransport,
  did:web/did:dns/VC, Google ADK and OpenAI adapters, A2A v1.0 compat
- deployment.md: add MCP/ANP/federation config sections, updated env vars
  and TOML config, new metrics, WebTransport
- protocol.md: add federation.proto (FederationService 2 RPCs), updated
  P2PExtension fields, WebTransport transport
- python-sdk.md: add AgentCard did_web/did_dns/VC fields, did:web functions,
  ADK/OpenAI adapters, A2A v1.0 compat, OASF module
- examples.md: add Google ADK and OpenAI Agents SDK integration examples,
  updated DID example with did:web
- getting-started.md: add TypeScript install, Go version bump, new adapters
- README.md: restore Three Ways / Interoperability / Relay sections with
  updated content, balance comprehensiveness with readability

Author: gk16

README.md

@@ -52,33 +52,38 @@ The daemon is the P2P engine. Internal packages:
 |---|---|
 | `internal/a2a/` | A2A protocol engine — task state machine, envelope routing, offline queue, streaming |
 | `internal/node/` | libp2p host — peer connections, mDNS discovery, DHT, stream multiplexing |
-| `internal/crypto/` | Ed25519 key management, Noise_XX integration |
+| `internal/crypto/` | Ed25519 key management, Noise_XX integration, DID conversion (did:key, did:web, did:dns), Verifiable Credentials |
 | `internal/nat/` | AutoNAT detection, DCUtR hole punching, Circuit Relay v2 client |
 | `internal/store/` | BoltDB persistence — tasks, agent cards, offline message queue |
 | `internal/config/` | Configuration — TOML file, environment variables, CLI flags |
 | `internal/bridge/` | HTTP Bridge — translates HTTP JSON-RPC ↔ P2P A2A envelopes |
-| `internal/anycast/` | Anycast router — skill-based addressing, registry + DHT discovery |
-| `internal/metrics/` | Prometheus metrics — connections, tasks, routing, bridge, streaming |
+| `internal/anycast/` | Anycast router — skill-based addressing, registry + multi-registry federation + DHT discovery |
+| `internal/metrics/` | Prometheus metrics — connections, tasks, routing, bridge, streaming, MCP |
+| `internal/mcp/` | MCP Server — exposes P2P capabilities as MCP tools (stdio + Streamable HTTP) |
+| `internal/anp/` | ANP Bridge — translates ANP HTTP ↔ A2A P2P (JSON-RPC 2.0 + JSON-LD) |
 | `pkg/grpcserver/` | gRPC server — 16 RPC methods exposed to the SDK |
 
 The daemon is started and stopped by the SDK. It runs as a local process, listening only on a Unix domain socket (or localhost TCP).
 
 ### Relay Server (`agentanycast-relay`)
 
-The relay provides two services:
+The relay provides three services:
 
 1. **Circuit Relay v2** — bridges agents across different networks with strict resource limits. The relay **cannot read traffic** — all communication is end-to-end encrypted before reaching the relay.
 
 2. **Skill Registry** — in-memory registry where agents register their skills and discover each other by capability. TTL-based expiration with heartbeat renewal.
 
+3. **Federation** — gossip-based synchronization across multiple relays for global agent discovery. Uses Last-Writer-Wins conflict resolution.
+
 ### Proto Definitions (`agentanycast-proto`)
 
 The single source of truth for all interfaces. Contains:
 
 - **`node_service.proto`** — 16 RPC methods between SDK and daemon
 - **`registry_service.proto`** — 4 RPC methods for skill registry on relay
+- **`federation.proto`** — 2 RPC methods for multi-relay registry synchronization
 - **`a2a_models.proto`** — Task, Message, Part, Artifact, A2AEnvelope (11 envelope types)
-- **`agent_card.proto`** — A2A-compatible capability descriptor with P2P extension
+- **`agent_card.proto`** — A2A-compatible capability descriptor with P2P extension (did:key, did:web, did:dns, VCs)
 - **`streaming.proto`** — StreamStart, StreamChunk, StreamEnd for chunked delivery
 - **`common.proto`** — Shared types (PeerInfo, NodeInfo, TaskStatus)
 
@@ -198,7 +203,13 @@ Every node has an **Ed25519 key pair**, generated on first start and persisted i
 
 #### W3C DID Interop
 
-Peer IDs can be converted to W3C Decentralized Identifiers (`did:key:z6Mk...`) for interoperability with DID-based systems. The SDK provides `peer_id_to_did_key()` and `did_key_to_peer_id()` for bidirectional conversion.
+Peer IDs can be converted to multiple DID methods for interoperability:
+
+- **`did:key`** — derived directly from the Ed25519 public key (`did:key:z6Mk...`)
+- **`did:web`** — web-based DID resolution (`did:web:example.com:agents:myagent`)
+- **`did:dns`** — DNS-based DID resolution
+
+The SDK provides bidirectional conversion functions (`peer_id_to_did_key`, `did_web_to_url`, etc.). Agent Cards can also carry Verifiable Credentials for trust attestation.
 
 ### Encryption
 
@@ -232,7 +243,7 @@ Agents behind NATs or firewalls use a three-tier strategy:
 
 ### Tier 1: Direct Connection
 
-If both agents are on the same network (or have public IPs), they connect directly via TCP or QUIC.
+If both agents are on the same network (or have public IPs), they connect directly via TCP, QUIC, or WebTransport.
 
 ### Tier 2: Hole Punching (DCUtR)
 
@@ -337,19 +348,58 @@ If a message can't be delivered (peer is offline or unreachable), the daemon:
 
 This provides **at-least-once delivery** for A2A envelopes without requiring the application to implement retry logic. Messages expire after a configurable TTL (default 24 hours).
 
+## MCP Server
+
+The daemon can run as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, exposing P2P capabilities as tools for AI assistants like Claude Desktop, Cursor, VS Code, ChatGPT, and Gemini CLI.
+
+Two transport modes:
+- **stdio** — local integration (`agentanycastd -mcp`)
+- **Streamable HTTP** — remote clients (`agentanycastd -mcp-listen :3000`)
+
+Available tools: `toolGetNodeInfo`, `toolListConnectedPeers`, `toolGetAgentCard`, `toolDiscoverAgents`, `toolSendTask`, `toolSendTaskBySkill`, `toolGetTaskStatus`.
+
+The relay also exposes an MCP server with registry-specific tools (`discover_agents`, `list_skills`, `get_relay_info`).
+
+## ANP Bridge
+
+The [ANP (Agent Network Protocol)](https://www.w3.org/community/anp/) bridge enables interoperability with the W3C ANP ecosystem:
+
+- `GET /agent/ad.json` — Agent Description (JSON-LD)
+- `GET /agent/interface.json` — OpenRPC specification
+- `POST /agent/rpc` — JSON-RPC 2.0 endpoint
+
+## Multi-Relay Federation
+
+Multiple relay servers can synchronize their skill registries using gossip-based federation:
+
+1. Each relay periodically pulls updates from configured peer relays
+2. New registrations are pushed to peers
+3. Conflicts are resolved using Last-Writer-Wins with version counters
+4. Local registrations always take priority over federated ones
+
+This enables global agent discovery across relay clusters without a single point of failure.
+
 ## Interoperability
 
-### MCP (Model Context Protocol)
+### MCP Tool Mapping
 
 The SDK can map MCP tools to A2A skills and vice versa, enabling agents built on MCP to participate in the AgentAnycast network.
 
+### A2A v1.0 Protocol Compatibility
+
+The Python SDK includes a compatibility layer (`compat/a2a_v1.py`) for bidirectional conversion between internal models and the official A2A v1.0 JSON format.
+
+### OASF (Open Agentic Schema Framework)
+
+Agent Cards can be converted to/from OASF records for publishing to the AGNTCY Agent Directory Service.
+
 ### AGNTCY Directory
 
 The SDK can query the AGNTCY agent directory for cross-ecosystem discovery, finding agents registered in external directories.
 
 ### Framework Adapters
 
-Built-in adapters for CrewAI and LangGraph wrap existing framework instances as P2P-capable agents, requiring minimal code changes.
+Built-in adapters for CrewAI, LangGraph, Google ADK, and OpenAI Agents SDK wrap existing framework instances as P2P-capable agents, requiring minimal code changes.
 
 ## gRPC Interface
 

docs/architecture.md

@@ -57,6 +57,10 @@ go build -o relay ./cmd/relay
 | `--max-reservations` | Max concurrent relay reservations | `128` |
 | `--registry-listen` | gRPC address for skill registry | `:50052` |
 | `--registry-ttl` | Skill registration TTL | `30s` |
+| `--enable-webtransport` | Enable WebTransport (QUIC-based) | `false` |
+| `--mcp-listen` | MCP Streamable HTTP listen address | `:8080` |
+| `--federation-peers` | Comma-separated peer relay gRPC addresses | (none) |
+| `--federation-sync-interval` | Federation gossip sync interval | `10s` |
 | `--log-level` | Log level (`debug`, `info`, `warn`, `error`) | `info` |
 
 ### Relay Resource Limits
@@ -107,47 +111,63 @@ CLI flags > environment variables > config file > defaults
 | Variable | Description | Default |
 |---|---|---|
 | `AGENTANYCAST_KEY_PATH` | Identity key file path | `~/.agentanycast/key` |
-| `AGENTANYCAST_GRPC_LISTEN` | gRPC listen address | `127.0.0.1:50051` |
+| `AGENTANYCAST_GRPC_LISTEN` | gRPC listen address | `unix://~/.agentanycast/daemon.sock` |
 | `AGENTANYCAST_LOG_LEVEL` | Log level | `info` |
-| `AGENTANYCAST_STORE_PATH` | BoltDB store path | `~/.agentanycast/store` |
+| `AGENTANYCAST_STORE_PATH` | BoltDB store path | `~/.agentanycast/data` |
 | `AGENTANYCAST_BOOTSTRAP_PEERS` | Comma-separated relay multiaddrs | (none) |
 | `AGENTANYCAST_ENABLE_MDNS` | Enable mDNS discovery | `true` |
+| `AGENTANYCAST_REGISTRY_ADDRS` | Comma-separated registry addresses (federation) | (none) |
+| `AGENTANYCAST_MCP_LISTEN` | MCP Streamable HTTP address | (none) |
 
 ### Config File
 
 Default: `~/.agentanycast/config.toml`
 
 ```toml
 key_path = "~/.agentanycast/key"
-grpc_listen = "127.0.0.1:50051"
+grpc_listen = "unix://~/.agentanycast/daemon.sock"
 log_level = "info"
 log_format = "json"
-store_path = "~/.agentanycast/store"
+store_path = "~/.agentanycast/data"
 enable_mdns = true
-bootstrap_peers = [
-    "/ip4/203.0.113.50/tcp/4001/p2p/12D3KooW..."
-]
+enable_quic = true
+enable_webtransport = false
+enable_relay_client = true
+enable_hole_punching = true
+offline_queue_ttl = "24h"
+bootstrap_peers = ["/ip4/203.0.113.50/tcp/4001/p2p/12D3KooW..."]
 
-# HTTP Bridge — expose P2P agents via HTTP A2A endpoint
 [bridge]
 enabled = false
 listen = ":8080"
 # tls_cert = "/path/to/cert.pem"
 # tls_key = "/path/to/key.pem"
-# cors_origins = ["https://app.example.com"]
+# cors_origins = ["*"]
 
-# Anycast — skill-based routing
 [anycast]
-# registry_addr = "relay.example.com:50052"   # Relay's registry gRPC address
-enable_dht = false                             # Enable Kademlia DHT discovery
-dht_mode = "auto"                              # "auto", "server", or "client"
-cache_ttl = "30s"                              # Route cache TTL
-auto_register = true                           # Auto-register skills on startup
+routing_strategy = "random"
+cache_ttl = "30s"
+auto_register = true
+# registry_addr = "relay.example.com:50052"
+# registry_addrs = ["relay1:50052", "relay2:50052"]  # multi-relay federation
+enable_dht = false
+dht_mode = "auto"   # "auto", "server", or "client"
 
-# Prometheus Metrics
 [metrics]
 enabled = false
 listen = ":9090"
+
+[mcp]
+enabled = false
+listen = ":3000"
+
+[anp]
+enabled = false
+listen = ":8090"
+
+[identity]
+# did_web = "did:web:example.com:agents:myagent"
+# did_dns_domain = "example.com"
 ```
 
 ## HTTP Bridge
@@ -222,6 +242,54 @@ enable_dht = true
 cache_ttl = "30s"
 ```
 
+## MCP Server
+
+The daemon can run as an MCP (Model Context Protocol) server for AI tool integration.
+
+### stdio mode (Claude Desktop, Cursor, VS Code, Gemini CLI)
+
+```bash
+./agentanycastd -mcp
+```
+
+### Streamable HTTP mode (ChatGPT, remote clients)
+
+```toml
+[mcp]
+enabled = true
+listen = ":3000"
+```
+
+Or via CLI: `./agentanycastd -mcp-listen :3000`
+
+The relay also exposes an MCP server (default `:8080`) with registry-specific tools for agent discovery.
+
+## ANP Bridge
+
+The ANP (Agent Network Protocol) bridge enables interoperability with the W3C ANP ecosystem:
+
+```toml
+[anp]
+enabled = true
+listen = ":8090"
+```
+
+Exposes: `GET /agent/ad.json`, `GET /agent/interface.json`, `POST /agent/rpc`.
+
+## Multi-Relay Federation
+
+Multiple relays can synchronize their registries for global agent discovery:
+
+```bash
+# Relay 1
+./relay --key ./relay1.key --federation-peers "relay2.example.com:50052"
+
+# Relay 2
+./relay --key ./relay2.key --federation-peers "relay1.example.com:50052"
+```
+
+Agents registered on Relay 1 become discoverable via Relay 2, and vice versa. Conflicts are resolved using Last-Writer-Wins with version counters.
+
 ## Prometheus Metrics
 
 Enable observability with Prometheus:
@@ -247,6 +315,8 @@ Available metrics:
 | `agentanycast_stream_chunks_total` | Counter | Streaming chunks sent/received |
 | `agentanycast_messages_total` | Counter | A2A messages by type |
 | `agentanycast_offline_queue_size` | Gauge | Queued offline messages |
+| `agentanycast_connections_by_transport` | Counter | Connections by transport (tcp/quic/webtransport) |
+| `agentanycast_mcp_tool_calls_total` | Counter | MCP tool calls by tool and status |
 
 ### Running Multiple Nodes on One Machine
 

docs/deployment.md

@@ -338,6 +338,58 @@ asyncio.run(main())
 
 Install: `pip install agentanycast[langgraph]`
 
+## Google ADK Integration
+
+Expose a Google ADK agent as a P2P agent.
+
+```python
+import asyncio
+from google.adk import Agent
+from agentanycast import AgentCard, Skill
+from agentanycast.adapters.adk import serve_adk_agent
+
+agent = Agent(name="assistant", model="gemini-2.0-flash", ...)
+
+card = AgentCard(
+    name="ADKAgent",
+    description="An agent powered by Google ADK",
+    skills=[Skill(id="assist", description="General assistance")],
+)
+
+async def main():
+    await serve_adk_agent(agent, card=card, relay="...")
+
+asyncio.run(main())
+```
+
+Install: `pip install agentanycast[google-adk]`
+
+## OpenAI Agents SDK Integration
+
+Expose an OpenAI agent as a P2P agent.
+
+```python
+import asyncio
+from agents import Agent
+from agentanycast import AgentCard, Skill
+from agentanycast.adapters.openai_agents import serve_openai_agent
+
+agent = Agent(name="assistant", instructions="You are a helpful assistant.", model="gpt-4o")
+
+card = AgentCard(
+    name="OpenAIAgent",
+    description="An agent powered by OpenAI",
+    skills=[Skill(id="assist", description="General assistance")],
+)
+
+async def main():
+    await serve_openai_agent(agent, card=card, relay="...")
+
+asyncio.run(main())
+```
+
+Install: `pip install agentanycast[openai-agents]`
+
 ## MCP Tool Mapping
 
 Convert MCP (Model Context Protocol) tools into A2A skills:
@@ -369,19 +421,21 @@ Work with W3C Decentralized Identifiers alongside Peer IDs:
 
 ```python
 from agentanycast.did import peer_id_to_did_key, did_key_to_peer_id
+from agentanycast.did import did_web_to_url, url_to_did_web
 
-# Convert Peer ID to DID
-did = peer_id_to_did_key("12D3KooWAbCdEf...")
-print(did)  # "did:key:z6MkhaXgBZ..."
+# did:key — derived from Ed25519 public key
+did = peer_id_to_did_key("12D3KooWAbCdEf...")   # "did:key:z6Mk..."
+peer_id = did_key_to_peer_id("did:key:z6Mk...")  # "12D3KooWAbCdEf..."
 
-# Convert DID back to Peer ID
-peer_id = did_key_to_peer_id("did:key:z6MkhaXgBZ...")
-print(peer_id)  # "12D3KooWAbCdEf..."
+# did:web — web-based DID resolution
+url = did_web_to_url("did:web:example.com:agents:myagent")
+# "https://example.com/agents/myagent/did.json"
 
-# The AgentCard also includes the DID
+# The AgentCard includes all DID methods
 async with Node(card=card) as node:
     remote_card = await node.get_card("12D3KooW...")
     print(remote_card.did_key)  # "did:key:z6Mk..."
+    print(remote_card.did_web)  # "did:web:example.com:agents:myagent"
 ```
 
 ## Cross-Network Communication