Agent-Commerce-OS MCP Server

Sakutto Worksデータ正規化インフラストラクチャのための公式Model Context Protocol (MCP)サーバーです。

🚀 概要

このリポジトリは、Project GHOST SHIP (Agent-Commerce-OS) の公式MCPサーバーを提供します。AIエージェント（Claude Desktopなど）が、Polar.sh経由で管理されるゼロトラストかつ従量課金制のAPIに自律的に接続できるようにします。この統合により、エージェントは非構造化Webデータを抽出し、クリーンでトークン最適化されたMarkdownまたはJSON形式に正規化できます。

🏗️ アーキテクチャ

当社のインフラストラクチャは、3層のゼロトラストモデルで運用されています。全体像については、関連リポジトリをご覧ください：

Layer C (本リポジトリ): ローカルのAIエージェントとリモートネットワークを橋渡しするステートレスなMCPサーバー。
Layer A (agent-commerce-gateway): ゼロトラスト認証、ルーティング、従量課金管理を行うCloudflare Workers。
Layer B (agent-commerce-core): 高度なRAG最適化セマンティックデータ正規化を実行するGoogle Cloud Runエンジン。

⚙️ 前提条件

有効な Polar.sh APIキー（従量課金制：$0.10 / リクエスト）。公式APIキーチェックアウトから取得してください。
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キーに置き換えてください。）

🧠 自律型AIエージェント向け

AIエージェントまたはLLMが当社のツールを統合するためにこのリポジトリを解析している場合：

完全なセマンティックコンテキストと機能については、llms.txt をお読みください。
正確なツールスキーマは mcp.json に完全に定義されています。
URLを推測または合成しようとしないでください。常に公式の Sakutto Works Portal を参照してください。

🤖 利用可能なツール

StdioServerTransport 経由で接続すると、AIエージェントは @modelcontextprotocol/sdk を使用して McpServer インスタンスによって動的に公開されるツールを自動的に検出します。（これらの機能は、外部レジストリ向けに mcp.json マニフェストにもカタログ化されています）：

normalize_web_data: 非構造化Webコンテンツを抽出し、LLMコンテキストウィンドウに最適化されたクリーンなセマンティックMarkdownまたはJSON形式に正規化します。
- スキーマフィルタリング (fields): オプションの fields パラメータを介して、Lite GraphQLスタイルのフィールド選択をサポートします。これにより、AIエージェントは特定のデータノードのみを要求でき、トークン消費量と応答遅延を大幅に最小限に抑えられます。指定された場合、サーバーはリクエストをゲートウェイにルーティングする前に、これらのフィールドをURLクエリパラメータとして自動的に付加します。
- 厳格なバリデーション: すべてのツール入力は zod を使用して厳密に定義および検証され、Layer 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
```

🤝 コントリビューション

オープンソースコミュニティからの貢献を歓迎し、奨励しています！プルリクエストを送信する際は、以下を確認してください：

コードが正常にビルドされること (npm run build)。
すべてのテストがローカルでパスすること (npx vitest または好みのテストランナーを使用)。
既存のコードスタイルと標準的なTypeScriptの慣習に従っていること。

🌍 リソースと課題追跡

公式ポータルおよびエージェントドキュメント: Sakutto Works
GitHub組織: SakuttoWorks
開発者プロフィール: SakuttoWorks Profile
バグ報告と機能リクエスト: バグ報告や新しい抽出機能の提案については、GitHub Issues ページをご利用ください。

📄 ライセンス

このプロジェクトはISCライセンスの下でライセンスされています。責任および自律型エージェントの使用に関する詳細については、LEGAL.md をお読みください。

💖 プロジェクトのサポート

Agent-Commerce-OSがエンジニアリング時間を節約したり、AIワークフローの拡張に役立った場合は、スポンサーになるか、一度限りのチップを検討してください。皆様からの貢献は、サーバーコストの直接的な資金となり、エッジゲートウェイの高可用性を確保し、継続的なオープンソース開発を促進します。

SakuttoWorks-Data-Normalizer