Contextual MCP Server

Contextual MCP Server

一个使用 Contextual AI 提供 RAG（检索增强生成）能力的 Model Context Protocol（MCP）服务。该服务可与多种 MCP 客户端集成。你可以灵活决定服务提供哪些功能。在本 README 中，我们将展示如何与 Cursor IDE 和 Claude Desktop 集成。

Contextual AI 现在在其平台内提供托管服务，地址为：https://mcp.app.contextual.ai/mcp/
连接到该服务后，你可以使用平台 MCP 服务提供的工具，例如 query。
如需完整的操作指南，请参阅 MCP 用户指南。

概述

MCP 服务充当 AI 界面（Cursor IDE 或 Claude Desktop）与专用 Contextual AI Agent 之间的桥梁。它支持：

1. 查询处理：将特定领域的问题发送给专用的 Contextual AI Agent
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 Agent。

查询工具的文档字符串至关重要，因为它能帮助 MCP 客户端判断何时将问题路由到你的 RAG Agent。请针对你的知识领域进行具体描述。以下是一个示例：

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

或

A research tool focused on technical documents for Omaha semiconductors

该服务还需要以下 RAG Agent 设置：

• API_KEY：你的 Contextual AI API 密钥
• AGENT_ID：你的 Contextual AI Agent ID

如果你想将这些值存储在 .env 文件中，可以按如下方式指定：

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

该仓库还包含适用于多 Agent 系统的更多高级 MCP 服务，以及一个 document-agent。

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 能力，并提供多种可由 MCP 客户端访问的命令，例如 Cursor IDE 和 Claude Desktop。 当前服务主要使用 Contextual AI Python SDK 中的 query 命令，但你也可以扩展它以支持其他功能，例如列出所有 Agent、更新检索设置、更新提示词、提取检索结果或下载指标。

使用示例

# 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. 提供清晰的文档字符串，描述工具的功能

示例：

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

限制

• 服务在本地运行，在远程开发环境中可能无法正常工作
• 工具响应受 Contextual AI API 限制和配额约束
• 目前仅支持 stdio 传输模式

如需了解 Contextual AI 的所有功能，请查阅官方文档。