JPYC Agent MCP

JPYC Agent MCP

JPYC Agent MCP 既可作为公共 MCP 端点使用，也可作为 Codex 插件包使用。 此仓库现在以仓库根目录作为插件根目录，Codex 可以直接发现它。

支持的功能

• 创建和查找 Polygon Agent 钱包
• 查看钱包余额
• JPYC 转账报价和执行流程
• 合约读取调用
• 合约写入报价和执行流程
• 跟踪转账和合约调用状态

插件布局

Codex 应通过以下文件从仓库根目录发现插件：

• .codex-plugin/plugin.json
• .mcp.json
• skills/jpyc-agent-mcp/SKILL.md
• skills/jpyc-agent-mcp/agents/openai.yaml
• config/default.json

公共端点

• MCP 端点：https://jpyc-info.com/api/jpyc-agent-mcp
• OAuth 颁发者：https://jpyc-info.com/api/jpyc-agent-oauth
• 资源元数据：https://jpyc-info.com/.well-known/oauth-protected-resource
• 授权服务器元数据：https://jpyc-info.com/.well-known/oauth-authorization-server
• OpenID 配置：https://jpyc-info.com/.well-known/openid-configuration
• 人工登录页面：https://jpyc-info.com/mcp/connect
• MCP Registry 认证文件：https://jpyc-info.com/.well-known/mcp-registry-auth

该端点受 OAuth 保护。用户必须登录并授予许可，才能执行私有钱包操作。 如果在浏览器中直接打开 MCP 端点，系统会将其重定向到 https://jpyc-info.com/mcp/connect。 如果 MCP 客户端收到 401 unauthorized，应遵循 WWW-Authenticate 和上述资源元数据来发现 OAuth 流程。 如果 ChatGPT/Codex 未自动显示完整授权 URL，请在浏览器中打开 https://jpyc-info.com/mcp/connect，将其作为标准的人工备用方式。低级别的手动认证流程仍可通过 /api/jpyc-agent-oauth/start 用于调试，但它不是主要文档所述的流程。使用低级别流程的客户端必须妥善保管返回的 auth_session_secret，并在轮询 /api/jpyc-agent-oauth/auth-session 时提供该值。

如需了解完整的 OAuth 规范和准确 URL，请参阅 docs/auth.md 和 config/oauth.json。

Claude Code

Claude Code 原生不支持 streamable-http MCP 服务。 请使用 mcp-remote 将 streamable-http + OAuth 桥接到 stdio。

快速开始

将以下内容添加到项目的 .mcp.json 或 ~/.claude/settings.json 中：

{
  "mcpServers": {
    "jpyc-agent-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://jpyc-info.com/api/jpyc-agent-mcp"
      ]
    }
  }
}

首次连接时，mcp-remote 会打开浏览器以获取 OAuth 授权。 完成身份验证后，所有工具即可立即使用。

客户端令牌持久化

此代码库定义了受 OAuth 保护的 MCP 端点，以及 Codex 发现所需的插件元数据。它不会代替 Codex、ChatGPT 或任何其他 MCP 客户端实现客户端凭据存储。

客户端的预期行为：

1. 针对 JPYC Agent OAuth 颁发方启动 OAuth 流程
2. 接收颁发的 bearer 令牌或等效的会话凭据
3. 将该凭据持久化到客户端的本地安全存储中
4. 在后续 MCP 调用中重复使用该凭据，调用地址为 https://jpyc-info.com/api/jpyc-agent-mcp
5. 使用 auth_status 验证恢复的会话

如果客户端可以完成浏览器登录，却无法在本地持久化并重复使用颁发的凭据，那么从用户的角度来看，该 MCP 集成并不完整。在这种情况下，应在 MCP 客户端实现中修复，而非在此代码库的服务端 OAuth 协议中修复。

对于本地操作员工作流，此代码库包含一些辅助工具，可使用 DPAPI 持久化颁发的刷新令牌，并在后续会话中重复使用：

• docs/local-token-cache.md
• scripts/jpyc_oauth_cache.py（Python，Windows）
• scripts/jpyc_oauth_cache.ps1（PowerShell，Windows）

MCP 注册表

此代码库包含 server.json，用于通过基于域名的命名空间 com.jpyc-info/jpyc-agent-mcp 将远程服务发布到公共 MCP 注册表。

对于基于 HTTP 的域名验证，请在 https://jpyc-info.com/.well-known/mcp-registry-auth 上托管确切的文本值 v=MCPv1; k=...; p=...。在 jpyc-info 部署中，该端点由 MCP_REGISTRY_AUTH 环境变量提供。

主要工具

• auth_status
• list_agent_wallets
• get_agent_wallet
• create_agent_wallet
• get_agent_wallet_balance
• quote_transfer
• transfer_jpyc
• list_transactions
• get_transfer_status
• read_contract
• quote_contract_write
• execute_contract_write
• list_contract_call_history
• get_contract_call_status

详细的请求和响应示例见 docs/tools.md。

推荐流程

1. 检查 auth_status
2. 使用 list_agent_wallets 查看钱包
3. 仅在需要时使用 create_agent_wallet 创建钱包
4. 转账前检查余额
5. 转账和合约写入均采用先报价再执行的方式

转账流程：

1. quote_transfer
2. transfer_jpyc

合约写入流程：

1. quote_contract_write
2. execute_contract_write

备注

• 此代码库不包含机密信息。
• 此代码库不包含私钥或签名材料。
• 随附的技能旨在让 Codex 始终在 JPYC Agent MCP 工具范围内操作。
• 更多详情请参阅 docs/auth.md、config/oauth.json 和 docs/openai-and-mcp.md。