Mcptest

🚀 MCP統合サーバー (Salesforce • Atlassian • Supabase)

このサーバーは、TypeScriptで構築されたモデルコンテキストプロトコル（MCP）サーバーです。Salesforce、Atlassian（Jira/Confluence）、および内部リソースを、エージェントが標準化された方法で呼び出せるツールやリソースとして提供します。

このREADMEでは以下の内容をカバーします:

• サーバーの機能
• 認証情報の設定方法
• ローカルでのビルドと実行方法
• デスクトップクライアントを使用せずにツールをスモークテストする方法
• 運用/セキュリティに関する注意事項

🚀 クイックスタート

概要

• 言語/ランタイム: Node 18以上（Node 20以上が推奨）で動作するTypeScript
• MCPトランスポート: stdio（MCPサーバーはクライアントによって起動され、標準入出力を介して通信します）
• 主要な統合: Salesforce REST、Jira/Confluence REST、Supabase（ロギング + サンプルリソース）
• 強化機能: タイムアウト付きの中央HTTPクライアント、基本的なログ編集、環境分離

リポジトリのレイアウト

MCPtest-main/
├─ mcp-server/
│  ├─ index.ts                 # MCPサーバー (stdio) のツール/リソース用ハンドラー
│  ├─ types.ts                 # ツール/リソースの型定義ヘルパー
│  ├─ runtime/
│  │  ├─ context.ts            # 中央環境 + Supabaseクライアント
│  │  └─ http.ts               # 共有axiosインスタンス (タイムアウト、適切なデフォルト値)
│  ├─ tools/
│  │  ├─ salesforce.ts         # salesforce_* ツール (クエリ/取得/検索 + 書き込み)
│  │  ├─ atlassian.ts          # jira_* / confluence_* ツール
│  │  ├─ analytics.ts          # Supabaseをバックエンドにしたサンプルツール
│  │  ├─ documents.ts          # Supabaseをバックエンドにしたサンプルドキュメントツール
│  │  └─ utilities.ts          # 計算、日付フォーマット、UUID生成、文字列ハッシュ化、HTTPリクエスト
│  ├─ resources/
│  │  ├─ salesforce.ts         # salesforce://* 読み取り専用リソース
│  │  ├─ atlassian.ts          # jira://* / confluence://* リソース
│  │  ├─ analytics.ts          # Supabaseからのanalytics://* リソース
│  │  └─ documents.ts          # Supabaseからのdocument://* リソース
│  └─ tsconfig.json
├─ scripts/
│  ├─ mcp-smoketest.mjs        # ヘッドレスツール呼び出しスクリプト (stdioを介してサーバーを起動)
│  └─ list-tools.mjs           # すべてのツール名を表示
├─ .env.example
├─ package.json
└─ README.md

前提条件

• Node.js 18以上（20以上が推奨）
• TypeScriptをサポートするエディタ
• （オプション）Salesforce、Jira、Confluence、Supabaseのアカウント/APIトークン

環境変数

プロジェクトのルートディレクトリにある .env.example を .env にコピーし、必要な情報を記入してください。使用する統合機能のみ設定する必要があります。

Supabase（ロギング + サンプルリソースに使用）

後方互換性のため、VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY も runtime/context.ts で読み取られますが、明確性のために SUPABASE_* の名前を使用することを推奨します。

Salesforce

Jira (Atlassian)

Confluence (Atlassian)

💡 使用アドバイス

書き込みパスを有効にする前に、読み取り専用のツール（クエリ、検索）から始めてください。

📦 インストール

プロジェクトのルートディレクトリで以下のコマンドを実行してください。

依存関係のインストール

npm install

MCPサーバーのビルド

npm run build:mcp

このコマンドはTypeScriptを mcp-server/dist/index.js にコンパイルします。

💻 使用例

ツールのスモークテスト（デスクトップクライアント不要）

スモークテストスクリプトは、stdioを介してMCPサーバーを起動し、指定されたツールを呼び出します。

利用可能なツールの表示（オプション）

node scripts/list-tools.mjs

安全なツールの呼び出し（utilities.ts から）

Mac/Linux

node scripts/mcp-smoketest.mjs calculate '{"expression":"2+2*5"}'

Windows PowerShell（引用符をエスケープ）

node scripts/mcp-smoketest.mjs calculate "{""expression"":""2+2*5""}"

統合ツールの呼び出し（.env が設定されている場合のみ）

Salesforce（読み取り専用）

node scripts/mcp-smoketest.mjs salesforce_query '{"query":"SELECT Id, Name FROM Account LIMIT 1"}'

Jira（検索）

node scripts/mcp-smoketest.mjs jira_search_issues '{"jql":"assignee = currentUser() ORDER BY created DESC"}'

期待される出力は、ツールの結果を含む content 配列を持つJSONです（テキストシリアライズされたJSON）。認証エラーが表示された場合は、.env を再確認してください。

🔧 技術詳細

動作原理（概要）

mcp-server/index.ts

JSON-RPC MCPサーバーをstdio上で起動し、以下のハンドラーを提供します。

• ListTools → すべてのツールを検出します（tools/ から）
• CallTool → ツール呼び出しを正しいハンドラーにルーティングします
• ListResources/ReadResource → 読み取り専用のドキュメント/分析/Salesforce/Atlassianリソースを公開します

mcp-server/runtime/context.ts

• 環境変数の解析
• Supabaseクライアントの作成

mcp-server/runtime/http.ts

• 20秒のタイムアウト
• 制御されたステータス処理

ツールは、設定されている場合、Supabaseの api_logs にログを記録します。引数は、機密情報を保存しないように小さな編集ヘルパーを通じて渡されます。

設定詳細

HTTPクライアント

mcp-server/runtime/http.ts は20秒のタイムアウトと友好的なステータス処理（validateStatus）を設定します。リトライが必要な場合は、一度だけaxiosインターセプターを追加してください。

ロギング

ツールハンドラーは、api_logs に行を挿入する logApiCall ヘルパーを呼び出します。トークンなどの機密フィールドは、挿入前に編集されます。

レスポンス

ツールは常に { content: [{ type: "text", text: "<JSON-string>" }] } を返します。これにより、クライアントのパースが実行環境間で予測可能になります。

📚 ドキュメント

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

• 読み取り専用から始める: salesforce_query や jira_search_issues などのツールから始め、後で書き込み（作成/更新/削除/遷移）を有効にしてください。
• 書き込みを保護する: 簡単なパターンは、confirm: "yes" または dryRun: true をデフォルトとして要求し、明示的に要求された場合のみ状態を変更する呼び出しを実行することです。（計画: Salesforce/Atlassianの書き込みツールに dryRun フィールドを追加）
• 最小限の権限を使用する: 各統合に必要な最小限のAPIスコープを使用してください。
• SupabaseでRLSを使用する: ANONキーを使用する場合は、ログが公開されないように行レベルセキュリティを設定してください。

トラブルシューティング

mcp-server/dist/index.js が見つからない

ビルドステップをスキップしたか、間違ったフォルダから実行しています。 解決策: npm run build:mcp を実行し、mcp-server/dist/index.js が存在することを確認してください。

応答が遅いまたはハングする

外部APIが遅い可能性があります。タイムアウトは20秒に設定されています。必要に応じて runtime/http.ts で調整してください。

認証エラー

.env を再確認してください。統合されていないツール（calculate）を試して、サーバー/クライアントの接続を確認してください。

ツールが見つからない

node scripts/list-tools.mjs を実行して正確なツール名を確認し、それをスモークテストに渡してください。

拡張

新しい統合を追加するには、mcp-server/tools/yourservice.ts に新しいファイルを作成し、構造化された結果を返すツールを登録してください。

読み取り専用のビューを公開するには、mcp-server/resources/yourservice.ts を使用して独自のURIスキーム（例: yourservice://…）を定義してください。

GUIエージェントランタイムまたはデスクトップクライアントを使用する場合は、node mcp-server/dist/index.js をMCP stdioサーバーとして指定してください。

スクリプトリファレンス

package.json（ルート）には以下のスクリプトが含まれています。

• build:mcp – MCPサーバーをコンパイルします。
• mcp:server – コンパイルされたサーバーを直接実行します（通常はクライアントによって起動されます）
• （オプション）tools – ツール名を一覧表示します。
• （オプション）smoke – スモークテストを実行するための省略形です。