AI导哈

多链代理文件存储框架

FOC MCP Stack是一个实现ERC-8004多链代理身份和MCP/A2A协议的Filecoin/IPFS操作框架，为开发者提供将IPFS内容固定到Filecoin的桥梁，同时保持跨链身份验证。

  • by SgtPooki
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 SgtPooki/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 <repo-url>
cd foc-mcp-stack
pnpm install

  2. 配置环境：

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

  3. 启动开发服务器：

    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 方法

方法 描述 状态
echo 测试端点 ✅
agent.info 代理信息 ✅
pin.add 将CID固定到IPFS 🚧
pin.status 检查引脚状态 🚧
index.run 开始索引作业 🚧
index.status 检查索引状态 🚧
verify.proof 验证 Filecoin 证明 🚧

🔌 MCP 工具

工具 描述 状态
项目 描述 类型
将CID添加到固定服务中 🚧 pin_status

| 获取引脚状态 | 🚧 |

# 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操作
  • Filecoin Pin（或译为“Filecoin 固定”）
  • [ ] 添加使用secp256k1的ECDSA签名
  • [ ] ERC-8004 注册表集成
  • [ ] 与Filecoin Pin CLI和GitHub Actions的集成
  • [ ] 速率限制和身份验证
  • [ ] 监控和可观测性
  • [ ] Docker 部署

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

IPFS / libp2p

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

文件。

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

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

相关 MCP