contextual-mcp-server

Contextual MCP Server

一个使用 Contextual AI 提供 RAG（检索增强生成）能力的模型上下文协议（MCP）服务。该服务可与多种 MCP 客户端集成。你可以灵活决定在服务中提供哪些功能。在本自述文件中，我们将展示如何与 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 能力，可提供多种命令，供 Cursor IDE 和 Claude Desktop 等 MCP 客户端使用。 当前服务主要使用 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 的所有功能，请查阅官方文档。