aspro-mcp

Model Context Protocolサーバーであり、Aspro.Cloud REST APIをLLMクライアント（Claude Desktop、Claude Codeなど）に公開します。サーバーにはOpenAPI仕様が同梱されているため、モデルはモジュール、エンティティ、メソッドを自律的に探索し、安全に呼び出すことができます。

特徴

• 自己記述型。 モデルは aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe を経由してAPIをブラウズし、その後に aspro_call を実行します。エンドポイントを暗記する必要はありません。

• 部分一致検索。 モジュール、エンティティ、メソッド、パス、説明、タグを対象とした検索が可能です。

• デフォルトでForm-urlencoded POSTに対応。 Asproが期待するコンテンツタイプに対応しており、配列やネストされたオブジェクトの処理も可能です。

• パスパラメータの置換。 /get/{id}、/update/{id}、/delete/{id} 等のパスパラメータを自動的に処理します。

• テナントごとの設定。 ASPRO_COMPANY（サブドメイン）または完全な ASPRO_BASE_URL を使用して設定可能です。

インストール

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

Node.js ≥ 18 が必要です。

設定

サンプル環境ファイルをコピーして記入してください：

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

APIキーは、Aspro.Cloudアカウントの 設定 → インテグレーション → API から取得してください。

クライアントへの接続

Claude Desktop / Claude Code

MCP設定にサーバーを追加します：

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

サーバーは、クライアントが起動した作業ディレクトリに関係なく、プロジェクトルートから .env を読み込みます。

その他のMCPクライアント

stdio経由でMCPをサポートするクライアントであれば、node dist/index.js（または npm start）を実行することで利用可能です。

公開されているツール

推奨されるフローは search/list_* → describe → call です。

開発

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

スモークテストはネットワークにアクセスしません。同梱されているOpenAPI仕様が解析可能か、操作が記述可能か、URLビルダーが正しい形式のURLを生成するかを確認します。

プロジェクト構成

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

セキュリティ上の注意

• APIキーは環境変数から読み込まれ、すべてのリクエストに ?api_key=... として付加されます。.env をコミットしないでください。

• サーバーには許可リストがありません。設定されると、仕様に記述されているすべてのエンドポイント（/delete/{id} などの破壊的なものを含む）を呼び出すことができます。必要な権限のみを持つ専用のAPIキーを使用してください。

• ツールの出力を信頼しないでください。Asproのエンティティ（カスタムフィールドの値、説明など）には、ユーザーが入力したコンテンツが含まれている可能性があります。

コントリビューション

IssueやPRを歓迎します。提出前に npm run build && npm run smoke を実行してください。

ライセンス

MIT — LICENSE を参照してください。

aspro-mcp は非公式のサードパーティ製コネクタであり、Aspro.Cloudとは提携していません。