ariffazil/FORGE-mcp-a2a-agentic

⚒️ MCP + A2A Agentic — Protocol Integration

DITEMPA BUKAN DIBERI — Forged, Not Given.

Purpose

Implement MCP server/client patterns and A2A agent-to-agent protocol integration across the federation. Handle tool surface discovery, capability drift detection, transport selection (stdio/HTTP), and agent card registration.

When to Use

• Creating or modifying an MCP server for any federation organ (FastMCP, Express)
• Implementing A2A agent cards and task lifecycle
• Tool discovery — tools/list patterns, capability enumeration
• Transport decisions — stdio vs HTTP SSE vs streamable HTTP
• Drift detection between registered manifest and live tool surface

When NOT to Use

• Frontend UI components — use nextjs-mastery or react-spa-discipline
• Database or cache layers — use postgres-schema-design or redis-qdrant-integration
• Deployment — use cicd-docker-deploy

Constitutional Floor Alignment

| Floor | Application | |-------|-------------| | F1 AMANAH | Tool renames are breaking changes; deprecate before removal across one cycle | | F2 TRUTH | Tool descriptions must match actual behavior — vague descriptions = silent misfires | | F3 WITNESS | A2A agent cards published with verifiable identity (did:web ref) | | F4 CLARITY | One tool = one responsibility; no mega-tools with action-switch parameters | | F11 AUDIT | Every tool call logged with actor, intent, timestamp, result | | F12 INJECTION | Tool arguments sanitized; no eval or raw shell from untrusted input |

Commands & Patterns

// FastMCP tool registration — FastMCP convention
server.tool(
  'forge_health_check',
  'Return A-FORGE server health and constitutional genome status',
  {
    include_latency: z.boolean().optional(),
  },
  async (args) => {
    // implementation
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  },
);

// A2A agent card — minimal structure
{
  "@context": "https://a2a.arif-fazil.com/schema/agent-card/v1",
  "id": "did:web:arif-fazil.com#333-agi",
  "name": "333-AGI",
  "capabilities": ["reason", "plan", "execute"],
  "services": [{
    "id": "#a2a-endpoint",
    "type": "A2AServer",
    "serviceEndpoint": "https://aaa.arif-fazil.com/a2a"
  }]
}

// Surface drift detection — compare manifest vs tools/list
// 1. Fetch manifest from federation-manifest
// 2. Call tools/list on each organ
// 3. Diff: missing tools, extra tools, description drift, schema drift
// 4. Report to forge_surface_guard

Refusal Surface

• ❌ Tool names that change semantics without deprecation cycle
• ❌ A2A cards without verifiable identity references
• ❌ Registering tools that haven't passed HARAM scan + forge_evaluate
• ❌ Exposing internal organ ports/db details in tool descriptions
• ❌ Mixing transport auth models — stdio for local, HTTP with session for remote