contextual-mcp-server

Contextual MCP Server

Contextual AI を使用して RAG（検索拡張生成）機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーは、さまざまな MCP クライアントと連携します。サーバーで提供する機能は柔軟に選択できます。この README では、Cursor IDE と Claude Desktop の両方との連携方法を説明します。

Contextual AI は現在、プラットフォーム内でホスト型サーバーを提供しており、次の URL から利用できます：https://mcp.app.contextual.ai/mcp/
サーバーに接続すると、プラットフォームの MCP サーバーが提供する query などのツールを使用できます。
詳しい手順については、MCP のユーザーガイドをご覧ください。

概要

MCP サーバーは、AI インターフェース（Cursor IDE または Claude Desktop）と、特化した Contextual AI エージェントをつなぐブリッジとして機能します。次のことが可能になります：

1. クエリ処理：ドメイン固有の質問を、専用の Contextual AI エージェントに直接送信します
2. インテリジェントな検索：ナレッジベースに含まれる幅広い情報を検索します
3. コンテキストを考慮した応答：次の特徴を備えた回答を生成します：

• ソースドキュメントに基づいている
• 引用と出典を含んでいる
• 会話のコンテキストを維持する

連携の流れ

Cursor/Claude Desktop → MCP Server → Contextual AI RAG Agent
        ↑                  ↓             ↓                         
        └──────────────────┴─────────────┴─────────────── Response with citations

前提条件

• Python 3.10 以降
• Cursor IDE および／または Claude Desktop
• Contextual AI API キー
• MCP 対応環境

インストール

1. リポジトリをクローンします：

git clone https://github.com/ContextualAI/contextual-mcp-server.git
cd contextual-mcp-server

2. 仮想環境を作成して有効化します：

python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`

3. 依存関係をインストールします：

pip install -e .

設定

MCP サーバーの設定

このサーバーを使用するには、設定を変更する必要があります。 たとえば、single_agent サーバーでは、RAG エージェントに適した docstring にカスタマイズする必要があります。

クエリツールの docstring は、MCP クライアントがいつ質問を RAG エージェントに振り分けるべきかを理解するうえで重要です。ナレッジドメインに合わせて具体的に記述してください。例を示します：

A research tool focused on financial data on the largest US firms

または

A research tool focused on technical documents for Omaha semiconductors

また、サーバーには RAG エージェントから次の設定が必要です：

• API_KEY：Contextual AI API キー
• AGENT_ID：Contextual AI エージェント ID

これらの値を .env ファイルに保存する場合は、次のように指定できます：

cat > .env << EOF
API_KEY=key...
AGENT_ID=...
EOF

このリポジトリには、マルチエージェントシステム向けのより高度な MCP サーバーや、ドキュメントエージェントも含まれています。

AI インターフェースとの連携

この MCP サーバーは、さまざまなクライアントと連携できます。Cursor IDE または Claude Desktop で使用するには、適切な場所にある MCP 設定ファイルを作成または変更します：

1. まず、uv のインストール先を確認します：

UV_PATH=$(which uv)
echo $UV_PATH
# Example output: /Users/username/miniconda3/bin/uv

2. 手順 1 で確認したフルパスを使用して、設定ファイルを作成します：

cat > mcp.json << EOF
{
 "mcpServers": {
   "ContextualAI-TechDocs": {
     "command": "$UV_PATH", # make sure this is set properly
     "args": [
       "--directory",
       "\${workspaceFolder}",  # Will be replaced with your project path
       "run",
       "multi-agent/server.py"
     ]
   }
 }
}
EOF

3. 下記のオプションを参照し、正しいフォルダーに移動します：

mkdir -p .cursor/
mv mcp.json .cursor/

設定ファイルの場所：

• Cursor の場合：
• プロジェクト固有：プロジェクトディレクトリ内の .cursor/mcp.json
• グローバル：システム全体でアクセスするための ~/.cursor/mcp.json
• Claude Desktop の場合：
• 適切な Claude Desktop 設定ディレクトリに、同じ形式の設定ファイルを使用します

環境のセットアップ

このプロジェクトでは依存関係の管理に uv を使用します。これにより、Python パッケージをより高速かつ確実にインストールできます。

使用方法

このサーバーは Python SDK を使用して Contextual AI の RAG 機能を提供し、Cursor IDE や Claude Desktop などの MCP クライアントからさまざまなコマンドを利用できます。 現在のサーバーでは、Contextual AI Python SDK の query コマンドを使用していますが、エージェントの一覧表示、検索設定の更新、プロンプトの更新、検索結果の抽出、メトリクスのダウンロードなど、ほかの機能にも拡張できます。

使用例

# In Cursor, you might ask:
"Show me the code for initiating the RF345 microchip?"

# The MCP client will:
1. Determine if this should be routed to the MCP Server

# Then the MCP server will:
1. Route the query to the Contextual AI agent
2. Retrieve relevant documentation
3. Generate a response with specific citations
4. Return the formatted answer to Cursor

主なメリット

1. 正確な回答：すべての回答はドキュメントに基づいています
2. 情報源の明示：すべての回答に、参照したドキュメントが記載されています
3. コンテキストの認識：システムは会話のコンテキストを維持するため、追加の質問にも対応できます
4. リアルタイム更新：回答には、データストア内の最新のドキュメントが反映されます

開発

サーバーの変更

新しい機能を追加するには、次の手順に従います。

1. @mcp.tool() でデコレートした関数を追加して、新しいツールを作成します
2. Python の型ヒントを使用して、ツールのパラメーターを定義します
3. ツールの機能を説明する、わかりやすい docstring を記述します

例：

@mcp.tool()
def new_tool(param: str) -> str:
   """Description of what the tool does"""
   # Implementation
   return result

制限事項

• サーバーはローカルで実行されるため、リモート開発環境では動作しない場合があります
• ツールの応答には、Contextual AI API の制限とクォータが適用されます
• 現在は stdio トランスポートモードのみをサポートしています

Contextual AI のすべての機能については、公式ドキュメントをご確認ください。