meridian-mcp

@meridiantoolkit/mcp

Meridian ビジネスサービスプラットフォーム向けの MCP サーバーです。サービス、サービスリクエスト、ワークフローのステップ、支払い、ミーティングを、Model Context Protocol のツールおよびリソースとして公開します。MCP はプロトコルであり、特定のホスト専用のプラグイン形式ではありません。このサーバーは Claude Code、Codex CLI、Claude Desktop、pi、またはその他の MCP 互換クライアントで、変更なしで実行できます。

io.github.meridian-silkdev/meridian-mcp として公式 MCP Registry に登録されており、Glama にも掲載されています。

インストール

cd meridian-mcp
npm install
npm run build

または、公開後は次のコマンドを実行します。

npx @meridiantoolkit/mcp

設定

.env.example をコピーするか、環境変数を直接設定します。

変数	説明	デフォルト
MERIDIAN_API_URL	Meridian アプリのベース URL	http://localhost:3000
MERIDIAN_API_KEY	REST 呼び出しに使う mrd_ API キー（Better Auth）	(未設定 — 設定するまでツールはプレースホルダーのヒントを返します)
DATABASE_URL	省略可能な直接 DB アクセスのフォールバック
MERIDIAN_MCP_LOG_LEVEL	debug/info/warn/error	info

詳細：/.well-known/agent-configuration では、Agent Auth の検出機能（機能ベースの短期 JWT、デバイス認証／CIBA 承認）を公開します。エージェントは長期間有効な mrd_ キーか、スコープを指定した Agent Auth の許可のどちらかを使用できます。詳しくは meridian-skills の meridian-api スキルを参照してください。

MERIDIAN_API_KEY がなくても、すべてのツールは応答します。呼び出されるエンドポイントと必要な設定を説明するため、サーバーをドライラン／デモモードで安全に実行できます。

実行

npm start            # stdio MCP server
npm run dev          # watch mode via tsx

Claude Code

claude mcp add meridian -- node /absolute/path/to/meridian-mcp/dist/index.js
# or, once published:
claude mcp add meridian -- npx -y @meridiantoolkit/mcp

または、プロジェクトのルートに .mcp.json を置きます（チームで共有でき、Git にチェックインできます）。

{
  "mcpServers": {
    "meridian": {
      "command": "npx",
      "args": ["-y", "@meridiantoolkit/mcp"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}

Codex CLI

Codex は ~/.codex/config.toml（または信頼されたプロジェクトの場合は、プロジェクトスコープの .codex/config.toml）から MCP サーバーを読み込みます。

[mcp_servers.meridian]
command = "npx"
args = ["-y", "@meridiantoolkit/mcp"]
env = { MERIDIAN_API_URL = "http://localhost:3000", MERIDIAN_API_KEY = "..." }

CLI から追加することもできます：codex mcp add meridian -- npx -y @meridiantoolkit/mcp。同じ設定が Codex CLI、IDE 拡張機能、ChatGPT デスクトップアプリで共有されます。

Codex には（Claude Code や pi とは異なり）プラグイン／スキルのシステムがありません。meridian-plugin／meridian-skills に相当するものは、この MCP サーバーとプロジェクトガイダンスだけです。他の環境でスキルパッケージが提供するものと同じツール利用ガイダンスを使用するには、AGENTS.md.example をプロジェクトの AGENTS.md にコピーしてください。

Claude Desktop / pi

MCP 設定に追加します（Claude Desktop：claude_desktop_config.json、pi：.pi/settings.json → mcpServers、または pi --mcp）。

{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/absolute/path/to/meridian-mcp/dist/index.js"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}

pi --mcp meridian-mcp/dist/index.js
# or via npx after publish
npx @meridiantoolkit/mcp

ツール

ツール	説明
meridian_status	API の接続／設定を確認し、利用可能なツール／リソースを一覧表示します。パラメーターはありません。どのクライアントでも同じように動作します。これは pi 専用だった meridian-plugin の拡張ツール meridian_status に代わるもので、ステータス確認が特定のホストに依存しなくなります。
list_services	サービスを一覧表示します（フィルター：categorySlug、isActive、countryCode）
get_service	ID／スラッグでサービスを取得し、formConfig も取得します
list_categories	サービスカテゴリーを一覧表示します
list_service_requests	リクエストを一覧表示します（フィルター：status、customerId、providerId、limit）
get_service_request	ID でリクエストを取得し、ステップも取得します
create_service_request	リクエストを作成します（serviceId、answers、customTitle）
update_request_status	リクエストのステータスを更新します（advance_step を推奨）
get_workflow_status	現在のフェーズと、すべての requestSteps を取得します
advance_step	現在のステップを完了し、次のステップに進みます
list_request_steps	すべての RequestSteps を順番に一覧表示します
get_payment_status	リクエストに紐づく支払いレコードを取得します
verify_payment	Flouci（チュニジア国内）または Stripe（海外）を使ってサーバー側で検証します
list_meetings	ミーティングを一覧表示します（フィルター：serviceRequestId、status）
create_meeting	Teams ミーティングを作成し、招待を送信します
respond_to_meeting	出欠を ACCEPTED／DECLINED／PENDING で回答します

リソース

URI	説明
meridian://services	サービスカタログの JSON
meridian://workflow	ワークフローの基盤とフェーズ

開発

npm run typecheck
npm run build
npm test          # spawns the built server over stdio and exercises every tool/resource

公開

初回公開（手動で一度だけ実施します。スコープ付きパッケージは、レジストリに存在するまで Trusted Publishing を利用できません）：

npm login                     # once per machine
npm publish --access public

CI/CD

• .github/workflows/ci.yml — main へのプッシュごと、および PR ごとに実行されます：npm ci、型チェック、ビルド、npm test（実際の stdio スモークテストスイート）。
• .github/workflows/publish.yml — 公開済みの GitHub Release をトリガーに、テストスイート全体を再実行し、リリースタグが package.json のバージョンと一致することを確認してから、次の処理を行います：
  1. npm の Trusted Publishing（OIDC） を使って npm publish --provenance を実行します。作成やローテーションが必要な NPM_TOKEN シークレットはありません。
  2. mcp-publisher login github-oidc と mcp-publisher publish を使って、公式 MCP Registry の掲載情報を公開・更新します（こちらも OIDC を利用し、シークレットは不要です）。server.json のバージョンはリリースタグに自動で同期されます。このステップには continue-on-error: true が設定されています。レジストリは明示的にプレビュー段階にあるため、ここで問題が起きても実際の npm リリースが妨げられることはありません。

mcpName の要件： package.json には "mcpName": "io.github.meridian-silkdev/meridian-mcp" フィールドがあります。レジストリのパッケージバリデーターは、npm パッケージと GitHub で検証済みのサーバー ID が同じ所有者によって公開されていることを確認するために、このフィールドを必要とします。server.json でサーバー名を変更する場合は、このフィールドも更新してください。更新しないと公開時に 400 エラーになります。

既知の上流バグと回避策： 対話型の mcp-publisher login github デバイスフローは、GitHub 組織の名前空間で公開すると、確実に 403 エラーになります（メンバーシップが一般公開されていること、Owner ロールであることにかかわらず発生します。modelcontextprotocol/registry#1537 を参照。この記事の執筆時点で未解決です）。GitHub 組織内のリポジトリで実行される GitHub Actions ワークフローから github-oidc を使えば、人間のアカウントの組織一覧を確認するのではなく、ワークフローのリポジトリ ID を検証するため、この問題を完全に回避できます。そのため、レジストリへの公開ステップは手動のローカルコマンドではなく CI に配置されています。

初回の手動公開後に一度だけ行う設定： パッケージの npmjs.com ページで、Settings → Trusted Publisher → GitHub Actions に移動し、meridian-silkdev/meridian-mcp とワークフロー publish.yml を指定します。その後は、新しいバージョンのリリースは次の手順だけで完了します：

npm version patch   # or minor/major — bumps package.json + creates a git tag
git push --follow-tags
gh release create v0.1.3 --generate-notes   # publishing this release triggers both the npm and MCP Registry publish steps