Sakutto Works 数据标准化基础设施的官方模型上下文协议 (MCP) 服务器。
本仓库提供了 Project GHOST SHIP (Agent-Commerce-OS) 的官方 MCP 服务器。它使 AI 智能体（如 Claude Desktop）能够自主连接到我们通过 Polar.sh 管理的零信任、按量计费的 API。通过此集成，智能体可以将非结构化网页数据提取并标准化为整洁、Token 优化的 Markdown 或 JSON 格式。
Related MCP server: deltav-edge-mcp-server
🛡️ 零信任边缘安全： 在 Cloudflare 边缘提供严格的提示注入防护和边界防御。
🧩 MCP 原生： 与 Claude Desktop 等模型上下文协议客户端实现即时、无缝集成。
⚡ 轻量级 GraphQL 过滤： 传递可选的 fields 数组以仅提取智能体所需的精确数据节点，从而大幅减少上下文窗口的 Token 消耗。
💳 纯按量付费： 每次成功调用仅需 $0.10，由 Polar.sh 提供支持。无隐藏费用，无强制订阅。
🤖 自主错误恢复： 严格遵守 MCP 标准错误格式 (isError: true)。智能地从边缘网关中继 402 Payment Required 和 429 Too Many Requests 错误，使 AI 智能体能够自主引导人类用户解决预算不足问题或停止无限循环，无需开发人员干预。
🔍 分布式追踪与可观测性： 每个请求都被分配一个唯一的 trace_id，该 ID 会在整个基础设施（网关 -> 引擎 -> R2 审计日志）中传播。如果发生错误，此 Trace ID 会直接注入到智能体的文本响应中，从而实现即时的、精准的调试和企业级支持，无需手动查找日志。
🔄 高级路由（同步/异步与分层）： AI 智能体可以动态决定提取管道。通过提供 target_tier（例如：可操作数据、合规性检查），引擎会调整其架构。此外，通过传递 webhook URL，智能体可以将繁重的提取任务卸载到后台（接收即时的 202 Accepted 和作业 ID），从而防止 MCP 超时限制。如果未提供 webhook，系统将优雅地回退到同步执行。
我们的基础设施基于三层零信任模型运行。您可以浏览我们的相关仓库以获取完整视图：
C 层（本仓库）： 一个无状态的 MCP 服务器，连接您的本地 AI 智能体与我们的远程网络。
A 层 (agent-commerce-gateway)： 处理零信任身份验证、路由和按量计费的 Cloudflare Workers。
B 层 (agent-commerce-core)： 执行高级、RAG 优化的语义数据标准化的 Google Cloud Run 引擎。
Node.js（建议 v18 或更高版本）和 npm。
有效的 Polar.sh API 密钥（按量计费，每请求 $0.10）。请从 官方 API 密钥结账页面 获取。
Claude Desktop 或任何标准的 MCP 兼容客户端。
要授予您的 AI 智能体访问标准化工具的权限，请将以下配置添加到您的 claude_desktop_config.json 中：
~/Library/Application Support/Claude/claude_desktop_config.json
%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/v1/normalize_web_data"
}
}
}
}（注意：将 /absolute/path/to/ghost-ship-mcp-server 替换为您克隆仓库的实际绝对路径，并将 your_polar_api_key_here 替换为您有效的 Polar.sh API 密钥。）
如果您是正在解析本仓库以集成我们工具的 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 查询参数。
动态提取层级 (target_tier)：AI 智能体可以指定目标架构层级（a1、a2 等）以动态更改提取逻辑（例如：提取严格的可操作可用性数据与标准 Markdown）。
异步 Webhooks (webhook)：对于长时间运行的提取任务，智能体可以提供包含目标 URL 的 webhook 对象。服务器将立即返回一个 job_id，允许智能体在无需等待的情况下继续操作。容错设计： 如果智能体将 webhook URL 留空或完全省略，服务器将安全地忽略 webhook 负载并同步执行请求，实时返回提取的数据。
严格验证：所有工具输入均使用 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 工作流，请考虑成为赞助商或提供一次性小费。您的贡献将直接资助我们的服务器成本，确保边缘网关的高可用性，并推动持续的开源开发。
© 2026 Sakutto Works. 为智能体经济标准化语义网。
Extracts, sanitizes, and normalizes unstructured web content into clean Markdown or JSON. Highly optimized for LLM context windows. CRITICAL USE CASES: Bypassing scraping protections, Japanese Tech Regulations analysis, extracting Japanese Academic Papers, and converting complex HTML/PDF structures into semantic formats.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The target URL to extract and normalize. | |
| format_type | No | Desired output format. Supported values: 'json', 'markdown'. | |
| fields | No | Schema Filtering (Lite GraphQL): Array of fields to extract, minimizing token consumption. | |
| target_tier | No | Extraction schema tier (e.g., 'a1' for async processing, 'a2' for actionable data, 'a3' for compliance). Defaults to standard. | |
| webhook | No | Webhook configuration for asynchronous processing. Required if target_tier is 'a1'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It notes it's 'optimized for LLM context windows' and mentions 'bypassing scraping protections', which implies potential risk. But does not disclose auth needs, rate limits, or side effects beyond the listed use cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with core function and lists use cases in a structured way. Slightly verbose with capitalized 'CRITICAL USE CASES', but overall efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains output formats (Markdown/JSON) and use cases. It lacks error handling, size limits, or rate limit info, but for a web extraction tool, it provides sufficient context for an AI agent to decide usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds little beyond the schema, only emphasizing output format and use cases. Baseline 3 is appropriate as the schema already provides sufficient meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it extracts, sanitizes, and normalizes web content into Markdown/JSON, with specific use cases listed. Verb+resource+output are explicit, and no sibling tools exist to confuse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides critical use cases (bypassing scraping protections, Japanese content, complex conversions), giving context on when to use. However, no explicit when-not-to-use or alternatives are mentioned, but since no siblings, it's adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
normalize_web_data5 fields changedInput schema / properties / fields / descriptionPrevious value: -"Schema Filtering (Lite GraphQL): Comma-separated list of fields to extract, minimizing token consumption (e.g., 'title,content')."New value: +"Schema Filtering (Lite GraphQL): Array of fields to extract, minimizing token consumption."Input schema / properties / fields / itemsAdded value: +{
+ "type": "string"
+}Input schema / properties / fields / typePrevious value: -"string"New value: +"array"Input schema / properties / target_tierAdded value: +{
+ "description": "Extraction schema tier (e.g., 'a1' for async processing, 'a2' for actionable data, 'a3' for compliance). Defaults to standard.",
+ "type": "string"
+}Input schema / properties / webhookAdded value: +{
+ "additionalProperties": false,
+ "description": "Webhook configuration for asynchronous processing. Required if target_tier is 'a1'.",
+ "properties": {
+ "url": {
+ "description": "The webhook endpoint URL to receive async results.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}v1.0.0normalize_web_dataScored across 1 tool
With only one tool, there is no possibility of confusion between tools. The single tool has a clear, comprehensive purpose.
A single tool name presents no inconsistency issues. The naming is clear and descriptive of its function.
One tool for a broad scope that includes multiple specialized use cases (bypassing scraping protections, extracting academic papers, etc.) feels insufficient. The tool is expected to handle a wide range of operations, likely warranting a few more focused tools.
The tool covers the core extraction, sanitization, and normalization workflow. Minor gaps could exist around configuration options or error handling, but the main domain is addressed.
Cross-OEM industrial machine intelligence: identity, normalization, automation, attestation.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Edge content delivery for autonomous agents — signed manifests, A2A authentication
Blockchain SSN for AI agents. MCP gateway that blocks at the point of action, tamper evident audit.
