Agent-Commerce-OS MCP 服务器

这是 Sakutto Works 数据标准化基础设施的官方模型上下文协议 (MCP) 服务器。

🚀 概述

本仓库为 Project GHOST SHIP (Agent-Commerce-OS) 提供官方 MCP 服务器。它使 AI 智能体（如 Claude Desktop）能够自主连接到我们通过 Polar.sh 管理的零信任、按量计费 API。通过此集成，智能体可以将非结构化的网页数据提取并标准化为整洁、Token 优化的 Markdown 或 JSON 格式。

🏗️ 架构

我们的基础设施基于三层零信任模型运行。您可以浏览我们相关的仓库以获取完整视图：

C 层（本仓库）：一个无状态的 MCP 服务器，连接您的本地 AI 智能体与我们的远程网络。
A 层 (agent-commerce-gateway)：处理零信任身份验证、路由和按量计费的 Cloudflare Workers。
B 层 (agent-commerce-core)：执行高级、RAG 优化的语义数据标准化的 Google Cloud Run 引擎。

⚙️ 前置要求

有效的 Polar.sh API Key（按量计费，每请求 $0.10）。请从官方 API Key 结账页面获取。
Claude Desktop 或任何标准的 MCP 兼容客户端。

🔌 设置与配置 (Claude Desktop)

要授予您的 AI 智能体访问标准化工具的权限，请将以下配置添加到您的 claude_desktop_config.json 中：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-commerce-os": {
      "command": "node",
      "args": [
        "/absolute/path/to/ghost-ship-mcp-server/dist/index.js"
      ],
      "env": {
        "POLAR_API_KEY": "your_polar_api_key_here",
        "GATEWAY_URL": "https://api.sakutto.works"
      }
    }
  }
}

（注意：请将 /absolute/path/to/ghost-ship-mcp-server 替换为您克隆仓库的实际绝对路径，并将 your_polar_api_key_here 替换为您有效的 Polar.sh API Key。）

🧠 给自主 AI 智能体

如果您是正在解析本仓库以集成我们工具的 AI 智能体或 LLM：

请阅读我们的 llms.txt 以获取完整的语义上下文和功能说明。
确切的工具模式已在 mcp.json 中完整定义。
请勿尝试猜测或合成 URL。请始终参考官方 Sakutto Works 门户。

🤖 可用工具

一旦通过 StdioServerTransport 连接，AI 智能体将使用 @modelcontextprotocol/sdk 自动发现由 McpServer 实例动态公开的工具。（这些功能也已编入我们的 mcp.json 清单中，供外部注册表使用）：

normalize_web_data：将非结构化的网页内容提取并标准化为针对 LLM 上下文窗口优化的整洁语义 Markdown 或 JSON 格式。
- 模式过滤 (fields)：通过可选的 fields 参数支持轻量级 GraphQL 风格的字段选择。这允许 AI 智能体仅请求特定的数据节点，从而显著减少 Token 消耗并降低响应延迟。指定后，服务器会在将请求路由到网关之前，自动将这些字段附加为 URL 查询参数。
- 严格验证：所有工具输入均使用 zod 进行严格定义和验证，确保稳健地遵循 B 层的底层规范。验证通过后，服务器将使用您的 POLAR_API_KEY 进行身份验证，通过 HTTP POST 安全地将请求转发到网关。

💻 本地开发与设置

要在本地运行服务器或准备开发环境：

克隆仓库并进入目录：

git clone https://github.com/SakuttoWorks/ghost-ship-mcp-server.git
cd ghost-ship-mcp-server

安装所需的依赖项（包括 @modelcontextprotocol/sdk 和 zod）：
```
npm install
```
配置您的环境变量：
```
cp .env.example .env
```
（打开新创建的 .env 文件，插入您的 POLAR_API_KEY，并确保 GATEWAY_URL 设置为 https://api.sakutto.works 或特定的端点路径，例如 https://api.sakutto.works/v1/normalize_web_data。）
编译 TypeScript 源代码：
```
npm run build
```
启动 MCP 服务器：
```
npm start
```

🤝 贡献

我们欢迎并鼓励开源社区的贡献！在提交 Pull Request 时，请确保：

您的代码构建成功 (npm run build)。
所有测试在本地通过（使用 npx vitest 或您首选的测试运行器）。
您遵循现有的代码风格和标准 TypeScript 实践。

🌍 资源与问题追踪

官方门户与智能体文档： Sakutto Works
GitHub 组织： SakuttoWorks
开发者资料： SakuttoWorks Profile
错误报告与功能请求： 请使用我们的 GitHub Issues 页面报告任何错误或建议新的提取功能。

📄 许可证

本项目采用 ISC 许可证。有关责任和自主智能体使用的更多详细信息，请阅读我们的 LEGAL.md。

💖 支持项目

如果 Agent-Commerce-OS 为您节省了工程时间或帮助扩展了您的 AI 工作流，请考虑成为赞助商或留下一次性小费。您的贡献将直接资助我们的服务器成本，确保边缘网关的高可用性，并推动持续的开源开发。

SakuttoWorks-Data-Normalizer