Aspro.cloud Unofficial Mcp

aspro-mcp

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

特長

• 自己記述型。 モデルは aspro_search / aspro_list_* → aspro_describe を通じて API を調べてから呼び出すため、エンドポイントを覚えておく必要はありません。
• キーワード検索ではロシア語の語形変化に対応しているため、сделка、сделки、создать задачу のいずれも適切なエンドポイントにたどり着きます。
• 読み取りと書き込みは別々のツールです。 aspro_call は読み取り専用として注釈され、aspro_write は破壊的操作として注釈されます。そのためクライアントは、削除まで自動承認してしまうことなく、読み取りを自動承認できます。
• ASPRO_READ_ONLY=1 による読み取り専用モードでは、リクエストがプロセスの外に送信される前に、変更操作を拒否します。
• API キーがモデルに渡ることはありません。 ツールが返すすべての URL とエラーメッセージからキーが伏せられます。
• レスポンススキーマ。 aspro_describe は、エンドポイントが受け取るフィールドだけでなく、返すフィールドも報告します。
• デフォルトで application/x-www-form-urlencoded 形式の POST（Aspro が想定するコンテンツタイプ）に対応し、配列やネストされたオブジェクトも処理します。
• ASPRO_COMPANY（サブドメイン）または完全な ASPRO_BASE_URL によるテナントごとの設定。

インストール

チェックアウトせずに npm から直接実行できます。

npx -y aspro-mcp

公開パッケージは、ランタイム依存関係のない単一のバンドルファイルです。そのため npx が取得するパッケージは 1 つだけで、キャッシュが空の状態でも数秒でサーバーが起動します。

または、クローンしてビルドします。

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

Node.js ≥ 18 が必要です。

クライアントに接続する

Claude Desktop / Claude Code

認証情報を env ブロックに渡してください。これが推奨される設定であり、npx で動作する唯一の方法です。

{
  "mcpServers": {
    "aspro": {
      "command": "npx",
      "args": ["-y", "aspro-mcp"],
      "env": {
        "ASPRO_COMPANY": "your_company",
        "ASPRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

ローカルのチェックアウトを使う場合は、代わりにビルド済みのエントリーポイントを指定します。

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

その他の MCP クライアント

stdio 経由の MCP に対応するクライアントであれば、npx -y aspro-mcp（または node dist/index.js）を実行できます。

起動時に「Connection timed out」と表示される場合

0.2.1 以前のバージョンでは、約 100 個の推移的パッケージが取り込まれており、npx によるインストールに 30 秒以上かかることがありました。MCP クライアントの待機時間（Claude Code は 30 秒でタイムアウトします）を超えてしまうため、正常なサーバーが失敗したように表示されていました。0.2.2 以降は単一のバンドルファイルとして提供され、数秒で起動します。

クライアントが古いキャッシュ済みコピーを起動する場合は、"args": ["-y", "aspro-mcp@latest"] を指定して最新リリースを要求してください。npx を完全に介さないようにするには、パッケージを一度インストールして、バイナリを直接実行します。

npm install -g aspro-mcp

{
  "mcpServers": {
    "aspro": {
      "command": "aspro-mcp",
      "env": {
        "ASPRO_COMPANY": "your_company",
        "ASPRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

設定

設定は環境変数から取得されます。ローカルのチェックアウトでは、パッケージのルートにある .env ファイルも使用できます。このファイルは、クライアントの作業ディレクトリに関係なく読み込まれます。

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
# ASPRO_READ_ONLY=1               # optional; refuse create/update/delete entirely
# ASPRO_MAX_RESPONSE_CHARS=60000  # optional; cap on a single tool result

npx ではパッケージが npm キャッシュ内にあるため、読み込む .env ファイルはありません。上記の env ブロックを使用してください。環境にすでに設定されている変数は、常に .env より優先されます。

Aspro.Cloud アカウントの Settings → Integrations → API から API キーを取得してください。

認証情報がなくてもサーバーは起動し、同梱された仕様を使ってオフラインで動作する検出ツールを提供します。呼び出しツールのみが設定エラーを報告します。

公開されるツール

ツール	機能
aspro_list_modules	最上位モジュール（crm、fin、task、…）と、エンティティ／操作の件数を一覧表示します。
aspro_list_entities	モジュール内のエンティティと、それぞれで利用できるメソッドを一覧表示します。
aspro_list_methods	モジュールの操作（HTTP メソッド＋パス＋簡単な説明）を一覧表示します。エンティティによる絞り込みも可能です。
aspro_search	モジュール／エンティティ／メソッド／パス／説明／タグをキーワード検索します。
aspro_describe	1 つの操作のスキーマ全体を表示します。パラメーター、本文フィールド、レスポンスフィールド、データを変更するかどうかが含まれます。
aspro_call	読み取り（list／get）を実行します。{ status, ok, url, data } を返します。
aspro_write	作成／更新／削除を実行します。ASPRO_READ_ONLY が設定されている場合は登録されません。

推奨される流れは search／list_* → describe → call／write です。

セキュリティに関する注意事項

• Aspro は /delete/{id} を HTTP GET で提供します。 HTTP の動詞から、操作が破壊的かどうかは判断できません。そのため、これを基準に承認ルールを構築しないでください。このサーバーはメソッドのセグメントに基づいて操作を分類し、mutating として報告します。aspro_write には破壊的な操作を示す注釈が付与され、aspro_call はデータを変更する操作を拒否します。
• API キーは環境変数から読み込まれ、すべてのリクエストに ?api_key=... として追加されます。モデルに返される URL とエラーメッセージでは伏せられますが、クライアント設定には残るため、.env を絶対にコミットしないでください。
• エンドポイントごとの許可リストはありません。設定後は aspro_write から仕様書内のあらゆる変更操作エンドポイントにアクセスできます。必要最小限の権限を持つ専用の API キーを使い、モデルが書き込みを行う必要がない場合は ASPRO_READ_ONLY=1 を設定してください。
• ツールの出力は信頼できないものとして扱ってください。Aspro のエンティティ（カスタムフィールドの値、説明など）には、ユーザーが入力したコンテンツが含まれる場合があります。

同梱の仕様書に関する注意事項

仕様書にはクエリパラメーターが記載されていませんが、list エンドポイントは複数のパラメーターを受け付けます。これらは稼働中のテナントで確認済みで、サーバーの指示を通じてモデルに説明されます。

パラメーター	動作
page=N	1 始まりのページ番号です。
limit=N	ページ内の件数を減らします。値が大きくても、1 ページに含まれる項目は最大 25 件です。
filter[<field>]=v	レスポンスフィールドとの完全一致で絞り込みます。例：filter[id]=193。すべてのフィールドが絞り込み可能とは限りません。
search=<text>	エンティティ全体を全文検索します。

知っておくべき注意点が 2 つあります。

• 未知または非対応のクエリパラメーターはエラーにならず、黙って無視されます。 何も機能しないフィルターと、すべてに一致したフィルターは同じように見えるため、返された項目を確認してください。
• total はフィルター適用前の件数を示すため、フィルターに一致した行数は分かりません。

機能するソートパラメーターは見つかっていません。

アカウントごとのカスタムフィールド（cf_<id>／cf_<alias>）はテナントによって異なるため、仕様書には含まれていません。これらはレスポンスには含まれ、body で送信することもできます。

開発

npm run dev      # rebuild the bundle on change
npm run build    # tsc (type-check) + esbuild bundle
npm test         # smoke + e2e

npm run build は tsc で型チェックを行い、その後、esbuild を使ってサーバーと依存関係を dist/index.js にバンドルします（build.mjs を参照）。そのため、MCP SDK、zod、dotenv は devDependencies です。これらはコンパイルに含まれるため、ユーザーがインストールする必要はありません。ライセンス文は dist/THIRD_PARTY_LICENSES.txt にまとめられます。

どちらのテストスイートもネットワークには接続しません。npm run smoke は fetch をスタブ化し、バンドルされた仕様を解析できること、変更操作が正しく分類されること（GET で提供される削除操作を含む）、検索で想定されるエンドポイントが見つかること、URL が正しく構築されること、API キーがツールの結果やエラーに決して現れないこと、大きすぎるレスポンスが上限内に収まることを検証します。npm run e2e は、実際の MCP クライアントを使ってビルド済みサーバーを stdio 経由で起動し、公開されるツールとそのアノテーション、さらに ASPRO_READ_ONLY によって実際に aspro_write が利用できなくなることを確認します。

プロジェクト構成

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   environment loading and validation
  client.ts   HTTP client (URL building, redaction, form-urlencoded POSTs, timeouts, size caps)
  spec.ts     OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline unit tests
  e2e.ts      stdio round-trip against a real MCP client
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec
build.mjs     esbuild bundling + third-party license collection

コントリビューション

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

ライセンス

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

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