Foc MCP Stack

FOC MCP 栈（或堆叠）

A. Filecoin链上云（FOC） 实现代理框架 ERC-8004 对于多链代理身份和 MCP/A2A（在中文中，这通常被直接保留为原英文缩写，因为它是特定领域或技术中的专业术语，没有直接的中文对应翻译。不过，如果需要解释其含义，可以理解为“MCP（某系统或组件名称）/A2A（可能代表某种特定功能、接口或协议，具体含义需根据上下文确定）”。在没有具体上下文的情况下，保持原样使用MCP/A2A是常见的做法。） Filecoin/IPFS操作的协议。

这个代理提供了两者之间的桥梁 Filecoin Pin（或译为“Filecoin 固定”） 生态系统和多链应用，使开发者能够在保持跨多个区块链的链上身份的同时，利用加密保障将IPFS内容固定到Filecoin上。

🚀 快速入门

# Install dependencies
pnpm install

# Start the development server
pnpm dev

# Test the endpoints
curl http://localhost:3000/health
curl http://localhost:3000/.well-known/agent-card.json

建筑

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px"
  }
}}%%
flowchart TD

  %% ===== Repo (monorepo) =====
  subgraph REPO["FOC MCP Stack (this repo)"]
    A1["Apps: agent-service (A2A + MCP endpoints)"]:::repo
    P1["Packages: foc-mcp/core (signing & utils)"]:::repo
    P2["Packages: foc-mcp/chain-config (registry addresses)"]:::repo
    F1["Future: agent-registry / cards"]:::repo
  end

  %% ===== On-chain =====
  subgraph ONCHAIN["On-chain (ERC-8004)"]
    direction TB
    I1["Identity Registry (Base)"]:::onchain
    I2["Identity Registry (Sepolia)"]:::onchain
    I3["Identity Registry (Mainnet)"]:::onchain
  end

  %% Trust boundary (visual marker)
  B["Trust boundary (on-chain ↔ off-chain)"]:::boundary

  %% ===== Off-chain =====
  subgraph OFFCHAIN["Off-chain (descriptors + server)"]
    direction TB
    R["registration.json (same tokenURI for all chains)"]:::offchain
    C["agent-card.json (per-chain variants:\nA2A & MCP URLs,\npublic keys, chain info,\ncross-chain links)"]:::offchain
    S["Single MCP / A2A server (Fastify; chain-aware routing;\nFilecoin/IPFS ops; signs responses)"]:::offchain
  end

  %% External callers
  U["Clients / callers (agents, apps, UIs)"]:::caller

  %% Edges: repo → registries
  A1 --> I1
  A1 --> I2
  A1 --> I3

  %% Registries → registration.json
  I1 --> R
  I2 --> R
  I3 --> R

  %% registration → agent-card → server
  R --> C
  C --> S

  %% Callers ↔ Server (round-trip)
  U -->|HTTP A2A / WS MCP| S
  S -->|signed response| U

  %% Layout hints
  REPO --- ONCHAIN
  ONCHAIN --- B
  B --- OFFCHAIN

  %% Classes / styles
  classDef repo fill:#fff8e1,stroke:#f9a825,stroke-width:1px,color:#333;
  classDef onchain fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px,color:#1b5e20;
  classDef offchain fill:#e3f2fd,stroke:#1565c0,stroke-width:1px,color:#0d47a1;
  classDef boundary fill:#ffffff,stroke:#9e9e9e,stroke-dasharray: 5 5,color:#616161;
  classDef caller fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px,color:#4a148c;

📁 项目结构

foc-mcp-stack/
├── apps/
│   └── agent-service/          # Main MCP/A2A server
│       ├── src/
│       │   ├── server.ts       # Fastify server bootstrap
│       │   ├── routes/         # HTTP/WebSocket routes
│       │   │   ├── wellKnown.ts # Agent card endpoints
│       │   │   ├── a2a.ts      # A2A RPC methods
│       │   │   └── mcp.ts      # MCP WebSocket handler
│       │   ├── handlers/       # Business logic (TODO)
│       │   ├── middleware/     # Auth, rate limiting (TODO)
│       │   ├── schemas/        # Request/response schemas (TODO)
│       │   ├── signing/        # Response signing
│       │   └── utils/          # Helper functions (TODO)
│       └── package.json
├── packages/
│   ├── chain-config/           # Chain configurations
│   └── foc-core/              # Core types and utilities
├── deployments/
│   ├── cards/                 # Agent card JSON files
│   └── registration/          # ERC-8004 registration files
└── scripts/
    └── build-cards.ts         # Agent card builder

🛠️ 开发

先决条件

• Node.js 18及以上版本
• pnpm 9+（版本）

设置

1. 克隆并安装：

   git clone 
   cd foc-mcp-stack
   pnpm install

1. 配置环境：

   cp apps/agent-service/env.example apps/agent-service/.env
   # Edit .env with your configuration

1. 启动开发服务器：

   pnpm dev

可用脚本

• pnpm dev - 启动开发服务器
• pnpm build - 构建所有包
• pnpm typecheck - 对所有包进行类型检查
• pnpm lint - 检查所有包中的语法错误（或：lint所有包）

🌐 API 端点

健康检查

GET /health

代理卡（ERC-8004）

GET /.well-known/agent-card.json
GET /.well-known/agent-card-{chain}.json

A2A RPC（Asynchronous to Asynchronous Remote Procedure Call，异步到异步远程过程调用）

POST /a2a
Content-Type: application/json

{
  "method": "echo",
  "params": { "test": "hello" },
  "chainId": 84532,
  "agentId": "1"
}

MCP WebSocket（中文可译为：“MCP WebSocket（保持原样，或根据上下文可译为‘MCP的WebSocket’）”）

WS /mcp

🔧 配置

环境变量

# Server
PORT=3000
HOST=0.0.0.0
LOG_LEVEL=info
PUBLIC_URL=http://localhost:3000

# Agent Signing
SIGNER_PK=0x...  # Private key for signing responses

# RPC Endpoints
RPC_base-sepolia=https://sepolia.base.org
RPC_sepolia=https://sepolia.infura.io/v3/YOUR_KEY

支持的链

• Sepolia测试网（或Sepolia链） (84532)
• Sepolia（注：在区块链领域，Sepolia通常指的是以太坊的一个测试网络，但此处若仅作一般翻译，则为“塞波利亚”） 十一万五千五百一十一
• 基地 （8453）
• 以太坊主网 (1)

📋 A2A 方法

🔌 MCP 工具

| 获取引脚状态 | 🚧 |

# Build agent card for a specific chain
pnpm tsx scripts/build-cards.ts \
  --chain base-sepolia \
  --agentId 1 \
  --registry 0xREGISTRY_ADDR \
  --owner 0xOWNER_ADDR \
  --publicKey 0x04YOUR_PUBKEY \
  --publicUrl https://your-domain.com \
  --out deployments/cards/agent-card-base-sepolia.json

🏗️ 构建代理卡（或：创建智能体卡片）

• 🔐 安全
• 所有回复均使用代理的私钥签名
• 时间戳验证可防止重放攻击
• 链特定路由确保适当隔离

速率限制（待办事项）

• 🚧 路线图/发展蓝图 [\[ \] 使用\[具体工具或方法\]实施实际的Filecoin/IPFS操作](https://docs.filecoin.io/builder-cookbook/filecoin-pin#how-to-get-started)
• Filecoin Pin（或译为“Filecoin 固定”）
• \[ \] 添加使用secp256k1的ECDSA签名
• \[ \] ERC-8004 注册表集成
• \[ \] 与Filecoin Pin CLI和GitHub Actions的集成
• \[ \] 速率限制和身份验证
• \[ \] 监控和可观测性
• \[ \] Docker 部署

\[ \] 持续集成/持续交付（CI/CD）流水线

• 📚 参考文献
• ERC-8004：链上代理身份与发现
• 机器通信协议（MCP）
• Filecoin项目 Filecoin链上云（FOC）
• - 去中心化存储基础设施 Filecoin Pin 文档
• - 以加密保证将IPFS内容固定到Filecoin中

IPFS / libp2p

📄 许可证 MIT 许可证 - 请参阅 许可证

文件。

1. 👥 参与贡献
2. 为仓库创建分支（或：克隆仓库）
3. 创建一个特性分支
4. 做出你的更改
5. 如适用，请添加测试

______________________________________________________________________

提交拉取请求 维护者： 拉塞尔·邓普西（@sgtpooki）