# Context MCP
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/geq1fan/context-mcp/actions)
[](https://github.com/astral-sh/ruff)
> **项目上下文集成的 MCP 服务器**
>
> 为 AI Agent 提供安全的只读文件系统操作，用于分析和理解项目代码库，并兼容所有系统。
>
> 核心价值：
>
> - 轻量级项目检索，无需预先构建索引或部署额外服务。
> - 多仓库/多项目上下文聚合，通过 MCP 与 Agent 工作流顺畅衔接。
## 为什么选择 Context MCP？
**核心价值**：跨项目上下文聚合 — 在分析 A 项目时，一键获取 B 服务的接口实现、依赖库的源码逻辑。
### 多项目配置（一次配置，永久可用）
```json
{
"mcpServers": {
"frontend-project": {
"command": "uvx",
"args": ["context-mcp"],
"env": { "PROJECT_ROOT": "/path/to/frontend" }
},
"backend-api": {
"command": "uvx",
"args": ["context-mcp"],
"env": { "PROJECT_ROOT": "/path/to/backend" }
}
}
}
```
### 典型场景：微服务接口调用链分析
**问题**：前端调用 `POST /api/users/login` 返回 500 错误，需要排查后端实现
| 步骤 | 传统方案 | Context MCP |
| ------------- | -------------------------------------- | --------------------------------------------- |
| 1. 定位接口 | 手动打开后端项目 → 搜索路由文件 | 一句话："分析 login 接口的实现逻辑和错误处理" |
| 2. 追踪调用链 | 手动跟踪 routes → controller → service | Agent 自动跨项目搜索并追踪完整调用链 |
| 3. 理解逻辑 | 逐个打开文件查看参数验证、错误码 | 自动返回：参数规则、错误码含义、调用栈 |
| **总耗时** | **≈10 分钟**（需切换目录、多次搜索） | **≈30 秒**（Agent 自动化完成） |
**实际输出示例**：
```
🤖 已分析login接口完整调用链：
→ routes/users.js:12 定义POST /api/users/login
→ controllers/UserController.js:45 调用AuthService.login(email, password)
→ services/AuthService.js:78 参数验证：email必填且格式正确、密码8-20位
→ services/AuthService.js:92 错误码：401未授权、500数据库连接失败
当前500错误原因：数据库连接池配置过小，建议检查DB_POOL_SIZE环境变量
```
**价值**：将跨仓库代码追踪从"手动体力活"变为"AI 自动化"，团队协作效率提升 20 倍。
---
## 快速开始
### MCP 配置
```json
{
"mcpServers": {
"context-mcp": {
"command": "uvx",
"args": ["context-mcp"],
"env": {
"PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
}
```
或者：
```bash
claude mcp add context-mcp --env PROJECT_ROOT="/absolute/path/to/your/project" -- uvx context-mcp
```
> **⚠️ 注意**：`PROJECT_ROOT`变量必须配置，否则服务无法启动。
### 可选：安装性能优化工具
Context MCP 可以利用高性能命令行工具大幅提升搜索速度（**13 倍加速**），推荐安装：
**ripgrep（推荐）** - 文件内容搜索加速
```bash
# macOS
brew install ripgrep
# Windows (Scoop)
scoop install ripgrep
# Ubuntu/Debian
sudo apt install ripgrep
```
**fd（推荐）** - 文件名查找加速
```bash
# macOS
brew install fd
# Windows (Scoop)
scoop install fd
# Ubuntu/Debian
sudo apt install fd-find
```
> 💡 **提示**：这些工具是可选的。未安装时会自动降级到系统自带工具（grep/find），功能不受影响，只是速度稍慢。详细性能对比见[性能优化](#性能优化)章节。
### MCP Prompt
配置完成后，建议使用以下 Prompt 让 AI Agent **自主选择最合适的工具**，而非手动指定：
```
请先通过 get_tool_usage_guide 了解 context-mcp 提供的所有工具及其用途。
然后根据我的需求，自主选择最合适的工具组合来完成任务。
我的需求：[在此描述你的具体需求]
```
**这样做的优势：**
- ✅ **Agent 自主决策**：由 AI 判断用哪个工具最高效
- ✅ **工具组合优化**：自动串联多个工具完成复杂任务
- ✅ **适应性强**：即使工具升级或新增，无需修改 Prompt
---
## 核心能力
Context MCP 提供 **11 个 MCP 工具**，让 AI Agent 通过只读方式深入分析任何项目的代码库。
> **使用场景示例**：假设你已配置 `PROJECT_ROOT=/path/to/my-web-app`，以下是实际使用方式。
### 📁 导航工具（3 个）
- **`list_directory`** - 列出目录内容，支持排序和限制数量
- **场景**：初次接触项目，想了解整体结构
- **对话示例**：
```
👤 "列出这个 Web 项目的根目录文件"
🤖 [使用 list_directory] 显示：package.json, src/, public/, README.md...
```
- **`show_tree`** - 以树状结构展示目录层次，支持深度限制
- **场景**：可视化项目架构，生成文档
- **对话示例**：
```
👤 "显示 src/ 目录的完整结构，深度3层"
🤖 [使用 show_tree] 展示树状图，快速了解模块划分
```
- **`read_project_context`** - 读取项目的 AI 上下文文件（AGENTS.md, CLAUDE.md）
- **场景**：自动发现项目的 AI 协作规范和编码约定
- **对话示例**：
```
👤 "这个项目有配置 AI 协作规范吗？"
🤖 [使用 read_project_context] 发现 CLAUDE.md，包含代码风格、测试要求...
```
### 🔍 搜索工具（4 个）
- **`search_in_file`** - 在单个文件中搜索文本或正则表达式
- **场景**：已知文件，需要定位特定代码
- **对话示例**：
```
👤 "在 src/config/database.js 中搜索数据库连接配置"
🤖 [使用 search_in_file] 找到第23行的 DB_HOST 配置
```
- **`search_in_files`** - 跨多个文件递归搜索，支持正则表达式和排除模式
- **场景**：代码审计、追踪 API 调用、查找技术债务
- **对话示例**：
```
👤 "在整个项目中搜索所有 TODO 注释，排除 node_modules"
🤖 [使用 search_in_files] 发现15处待办事项，分布在8个文件中
👤 "查找项目中所有调用 fetch() 的地方"
🤖 [使用 search_in_files] 定位到23处 API 调用点
```
- **`find_files_by_name`** - 按文件名查找（支持通配符）
- **场景**：快速定位配置文件、测试文件
- **对话示例**：
```
👤 "找出这个 React 项目中所有的测试文件"
🤖 [使用 find_files_by_name "*.test.jsx"] 找到32个测试文件
👤 "项目里有几个 config.json 文件？"
🤖 [使用 find_files_by_name] 发现3个：根目录、src/config、tests/
```
- **`find_recently_modified_files`** - 按最近修改时间查找文件
- **场景**：了解项目最新进展、快速定位活跃代码
- **对话示例**：
```
👤 "这个项目最近一周改了哪些文件？"
🤖 [使用 find_recently_modified_files] 显示12个文件，主要集中在 auth 模块
```
### 📖 读取工具（4 个）
- **`read_entire_file`** - 读取完整文件内容
- **场景**：理解核心逻辑、分析配置
- **对话示例**：
```
👤 "读取这个项目的 package.json，告诉我用了哪些主要依赖"
🤖 [使用 read_entire_file] 分析依赖：React 18, Express 4.x, MongoDB...
```
- **`read_file_lines`** - 读取文件的指定行范围
- **场景**：精确查看函数实现
- **对话示例**：
```
👤 "src/utils/auth.js 的第 50-80 行是什么逻辑？"
🤖 [使用 read_file_lines] 这是 JWT token 验证函数...
```
- **`read_file_tail`** - 读取文件末尾 N 行
- **场景**：查看日志、检查文件最新内容
- **对话示例**：
```
👤 "看看 CHANGELOG.md 的最后20行，了解最新版本的改动"
🤖 [使用 read_file_tail] 最新版本 v2.1.0 增加了 OAuth 支持...
```
- **`read_files`** - 批量读取多个文件
- **场景**：对比分析、生成报告
- **对话示例**：
```
👤 "同时读取前端和后端的配置文件，对比环境变量设置"
🤖 [使用 read_files] 读取 client/.env 和 server/.env，发现不一致...
```
> 💡 **提示**：所有工具都经过安全加固，只支持只读操作，路径严格限制在配置的 PROJECT_ROOT 内。
## 性能优化
Context MCP 会优先使用高性能的命令行工具,当这些工具不可用时自动降级到标准工具或 Python 实现,确保在任何环境下都能正常工作。
### 性能对比
**基准测试环境**: 中型项目 (1000-10000 文件, 10MB-100MB)
| 操作 | 高性能工具 | 标准工具 | Python 实现 | 加速比 |
| ------------ | ----------------- | ----------- | ------------- | --------- |
| 文件内容搜索 | **ripgrep** 180ms | grep 2400ms | Python 4200ms | **13.3x** |
| 文件名查找 | **fd** 50ms | find 450ms | Python 680ms | **9.0x** |
### 推荐工具安装
为获得最佳性能,建议安装以下高性能工具:
#### ripgrep (rg) - 高性能搜索
**Windows**:
```powershell
# Chocolatey
choco install ripgrep
# Scoop
scoop install ripgrep
```
**Linux**:
```bash
# Ubuntu/Debian
sudo apt install ripgrep
# Fedora
sudo dnf install ripgrep
```
**macOS**:
```bash
brew install ripgrep
```
**官方下载**: https://github.com/BurntSushi/ripgrep#installation
#### fd - 高性能文件查找
**Windows**:
```powershell
# Chocolatey
choco install fd
# Scoop
scoop install fd
```
**Linux**:
```bash
# Ubuntu/Debian (需要 Ubuntu 19.04+ 或手动安装)
sudo apt install fd-find
# Fedora
sudo dnf install fd-find
```
**macOS**:
```bash
brew install fd
```
**官方下载**: https://github.com/sharkdp/fd#installation
> 📝 **说明**: 这些工具是可选的。Context MCP 在没有这些工具的环境下会自动降级到系统自带的 grep/find 或 Python 实现,功能完全不受影响,只是性能会有所降低。服务启动时会在日志中显示工具检测结果。
## 安全性
- **只读操作**：不提供写入、修改或删除功能
- **路径验证**：所有路径严格限制在配置的 PROJECT_ROOT 内
- **二进制文件保护**：拒绝将二进制文件作为文本读取
- **权限处理**：优雅处理权限错误
## 常见问题
## 开发指南
**贡献者快速开始：**
```bash
# 克隆并设置
git clone https://github.com/geq1fan/context-mcp.git
cd context-mcp
uv sync
# 运行测试
PROJECT_ROOT=$(pwd) uv run pytest
# 运行测试并生成覆盖率报告
PROJECT_ROOT=$(pwd) uv run pytest --cov=context_mcp
```
**测试覆盖率**：237 个测试（232 通过 + 5 跳过），覆盖率 78%（运行 `PROJECT_ROOT=$(pwd) python -m pytest --cov=context_mcp`）
## 文档
- **[README.md](README.md)** - 本文件，快速开始和概览
- **[SECURITY.md](SECURITY.md)** - 安全政策和漏洞报告
- **[CHANGELOG.md](CHANGELOG.md)** - 版本历史和变更记录
- **[LICENSE](LICENSE)** - MIT 许可证文本
## 系统要求
- Python 3.11 或更高版本
## 开源许可
MIT License - 完整内容请查看 [LICENSE](LICENSE) 文件。
- ✅ 允许商业使用、修改和分发
- ⚠️ 不提供任何担保
## 参与贡献
欢迎贡献！🎉
**快速贡献指南：**
1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/amazing-feature`）
3. 提交你的修改并添加测试
4. 确保所有测试通过（`PROJECT_ROOT=$(pwd) uv run pytest`）
5. 提交 Pull Request
## 支持与社区
- **问题反馈**：[GitHub Issues](https://github.com/geq1fan/context-mcp/issues)
- **讨论交流**：[GitHub Discussions](https://github.com/geq1fan/context-mcp/discussions)
- **安全漏洞**：参考 [SECURITY.md](SECURITY.md) 报告安全问题
---
**构建工具** [FastMCP](https://github.com/jlowin/fastmcp) • **适配平台** [Claude Desktop](https://claude.ai/desktop) • **基于协议** [MCP](https://modelcontextprotocol.io/)
Raw data
{
"_id": null,
"home_page": null,
"name": "context-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Context MCP Team <context-mcp@example.com>",
"keywords": "agent, ai, claude, code-analysis, context-integration, fastmcp, mcp, model-context-protocol",
"author": null,
"author_email": "Context MCP Team <context-mcp@example.com>",
"download_url": "https://files.pythonhosted.org/packages/61/f5/3662a1f0800045fa7807f023614ce5cbd5b36c4f6f5516268f52b5d5cd00/context_mcp-0.2.4.tar.gz",
"platform": null,
"description": "# Context MCP\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/geq1fan/context-mcp/actions)\n[](https://github.com/astral-sh/ruff)\n\n> **\u9879\u76ee\u4e0a\u4e0b\u6587\u96c6\u6210\u7684 MCP \u670d\u52a1\u5668**\n>\n> \u4e3a AI Agent \u63d0\u4f9b\u5b89\u5168\u7684\u53ea\u8bfb\u6587\u4ef6\u7cfb\u7edf\u64cd\u4f5c\uff0c\u7528\u4e8e\u5206\u6790\u548c\u7406\u89e3\u9879\u76ee\u4ee3\u7801\u5e93\uff0c\u5e76\u517c\u5bb9\u6240\u6709\u7cfb\u7edf\u3002\n>\n> \u6838\u5fc3\u4ef7\u503c\uff1a\n>\n> - \u8f7b\u91cf\u7ea7\u9879\u76ee\u68c0\u7d22\uff0c\u65e0\u9700\u9884\u5148\u6784\u5efa\u7d22\u5f15\u6216\u90e8\u7f72\u989d\u5916\u670d\u52a1\u3002\n> - \u591a\u4ed3\u5e93/\u591a\u9879\u76ee\u4e0a\u4e0b\u6587\u805a\u5408\uff0c\u901a\u8fc7 MCP \u4e0e Agent \u5de5\u4f5c\u6d41\u987a\u7545\u8854\u63a5\u3002\n\n## \u4e3a\u4ec0\u4e48\u9009\u62e9 Context MCP\uff1f\n\n**\u6838\u5fc3\u4ef7\u503c**\uff1a\u8de8\u9879\u76ee\u4e0a\u4e0b\u6587\u805a\u5408 \u2014 \u5728\u5206\u6790 A \u9879\u76ee\u65f6\uff0c\u4e00\u952e\u83b7\u53d6 B \u670d\u52a1\u7684\u63a5\u53e3\u5b9e\u73b0\u3001\u4f9d\u8d56\u5e93\u7684\u6e90\u7801\u903b\u8f91\u3002\n\n### \u591a\u9879\u76ee\u914d\u7f6e\uff08\u4e00\u6b21\u914d\u7f6e\uff0c\u6c38\u4e45\u53ef\u7528\uff09\n\n```json\n{\n \"mcpServers\": {\n \"frontend-project\": {\n \"command\": \"uvx\",\n \"args\": [\"context-mcp\"],\n \"env\": { \"PROJECT_ROOT\": \"/path/to/frontend\" }\n },\n \"backend-api\": {\n \"command\": \"uvx\",\n \"args\": [\"context-mcp\"],\n \"env\": { \"PROJECT_ROOT\": \"/path/to/backend\" }\n }\n }\n}\n```\n\n### \u5178\u578b\u573a\u666f\uff1a\u5fae\u670d\u52a1\u63a5\u53e3\u8c03\u7528\u94fe\u5206\u6790\n\n**\u95ee\u9898**\uff1a\u524d\u7aef\u8c03\u7528 `POST /api/users/login` \u8fd4\u56de 500 \u9519\u8bef\uff0c\u9700\u8981\u6392\u67e5\u540e\u7aef\u5b9e\u73b0\n\n| \u6b65\u9aa4 | \u4f20\u7edf\u65b9\u6848 | Context MCP |\n| ------------- | -------------------------------------- | --------------------------------------------- |\n| 1. \u5b9a\u4f4d\u63a5\u53e3 | \u624b\u52a8\u6253\u5f00\u540e\u7aef\u9879\u76ee \u2192 \u641c\u7d22\u8def\u7531\u6587\u4ef6 | \u4e00\u53e5\u8bdd\uff1a\"\u5206\u6790 login \u63a5\u53e3\u7684\u5b9e\u73b0\u903b\u8f91\u548c\u9519\u8bef\u5904\u7406\" |\n| 2. \u8ffd\u8e2a\u8c03\u7528\u94fe | \u624b\u52a8\u8ddf\u8e2a routes \u2192 controller \u2192 service | Agent \u81ea\u52a8\u8de8\u9879\u76ee\u641c\u7d22\u5e76\u8ffd\u8e2a\u5b8c\u6574\u8c03\u7528\u94fe |\n| 3. \u7406\u89e3\u903b\u8f91 | \u9010\u4e2a\u6253\u5f00\u6587\u4ef6\u67e5\u770b\u53c2\u6570\u9a8c\u8bc1\u3001\u9519\u8bef\u7801 | \u81ea\u52a8\u8fd4\u56de\uff1a\u53c2\u6570\u89c4\u5219\u3001\u9519\u8bef\u7801\u542b\u4e49\u3001\u8c03\u7528\u6808 |\n| **\u603b\u8017\u65f6** | **\u224810 \u5206\u949f**\uff08\u9700\u5207\u6362\u76ee\u5f55\u3001\u591a\u6b21\u641c\u7d22\uff09 | **\u224830 \u79d2**\uff08Agent \u81ea\u52a8\u5316\u5b8c\u6210\uff09 |\n\n**\u5b9e\u9645\u8f93\u51fa\u793a\u4f8b**\uff1a\n\n```\n\ud83e\udd16 \u5df2\u5206\u6790login\u63a5\u53e3\u5b8c\u6574\u8c03\u7528\u94fe\uff1a\n \u2192 routes/users.js:12 \u5b9a\u4e49POST /api/users/login\n \u2192 controllers/UserController.js:45 \u8c03\u7528AuthService.login(email, password)\n \u2192 services/AuthService.js:78 \u53c2\u6570\u9a8c\u8bc1\uff1aemail\u5fc5\u586b\u4e14\u683c\u5f0f\u6b63\u786e\u3001\u5bc6\u78018-20\u4f4d\n \u2192 services/AuthService.js:92 \u9519\u8bef\u7801\uff1a401\u672a\u6388\u6743\u3001500\u6570\u636e\u5e93\u8fde\u63a5\u5931\u8d25\n\n \u5f53\u524d500\u9519\u8bef\u539f\u56e0\uff1a\u6570\u636e\u5e93\u8fde\u63a5\u6c60\u914d\u7f6e\u8fc7\u5c0f\uff0c\u5efa\u8bae\u68c0\u67e5DB_POOL_SIZE\u73af\u5883\u53d8\u91cf\n```\n\n**\u4ef7\u503c**\uff1a\u5c06\u8de8\u4ed3\u5e93\u4ee3\u7801\u8ffd\u8e2a\u4ece\"\u624b\u52a8\u4f53\u529b\u6d3b\"\u53d8\u4e3a\"AI \u81ea\u52a8\u5316\"\uff0c\u56e2\u961f\u534f\u4f5c\u6548\u7387\u63d0\u5347 20 \u500d\u3002\n\n---\n\n## \u5feb\u901f\u5f00\u59cb\n\n### MCP \u914d\u7f6e\n\n```json\n{\n \"mcpServers\": {\n \"context-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"context-mcp\"],\n \"env\": {\n \"PROJECT_ROOT\": \"/absolute/path/to/your/project\"\n }\n }\n }\n}\n```\n\n\u6216\u8005\uff1a\n\n```bash\nclaude mcp add context-mcp --env PROJECT_ROOT=\"/absolute/path/to/your/project\" -- uvx context-mcp\n```\n\n> **\u26a0\ufe0f \u6ce8\u610f**\uff1a`PROJECT_ROOT`\u53d8\u91cf\u5fc5\u987b\u914d\u7f6e\uff0c\u5426\u5219\u670d\u52a1\u65e0\u6cd5\u542f\u52a8\u3002\n\n### \u53ef\u9009\uff1a\u5b89\u88c5\u6027\u80fd\u4f18\u5316\u5de5\u5177\n\nContext MCP \u53ef\u4ee5\u5229\u7528\u9ad8\u6027\u80fd\u547d\u4ee4\u884c\u5de5\u5177\u5927\u5e45\u63d0\u5347\u641c\u7d22\u901f\u5ea6\uff08**13 \u500d\u52a0\u901f**\uff09\uff0c\u63a8\u8350\u5b89\u88c5\uff1a\n\n**ripgrep\uff08\u63a8\u8350\uff09** - \u6587\u4ef6\u5185\u5bb9\u641c\u7d22\u52a0\u901f\n\n```bash\n# macOS\nbrew install ripgrep\n\n# Windows (Scoop)\nscoop install ripgrep\n\n# Ubuntu/Debian\nsudo apt install ripgrep\n```\n\n**fd\uff08\u63a8\u8350\uff09** - \u6587\u4ef6\u540d\u67e5\u627e\u52a0\u901f\n\n```bash\n# macOS\nbrew install fd\n\n# Windows (Scoop)\nscoop install fd\n\n# Ubuntu/Debian\nsudo apt install fd-find\n```\n\n> \ud83d\udca1 **\u63d0\u793a**\uff1a\u8fd9\u4e9b\u5de5\u5177\u662f\u53ef\u9009\u7684\u3002\u672a\u5b89\u88c5\u65f6\u4f1a\u81ea\u52a8\u964d\u7ea7\u5230\u7cfb\u7edf\u81ea\u5e26\u5de5\u5177\uff08grep/find\uff09\uff0c\u529f\u80fd\u4e0d\u53d7\u5f71\u54cd\uff0c\u53ea\u662f\u901f\u5ea6\u7a0d\u6162\u3002\u8be6\u7ec6\u6027\u80fd\u5bf9\u6bd4\u89c1[\u6027\u80fd\u4f18\u5316](#\u6027\u80fd\u4f18\u5316)\u7ae0\u8282\u3002\n\n### MCP Prompt\n\n\u914d\u7f6e\u5b8c\u6210\u540e\uff0c\u5efa\u8bae\u4f7f\u7528\u4ee5\u4e0b Prompt \u8ba9 AI Agent **\u81ea\u4e3b\u9009\u62e9\u6700\u5408\u9002\u7684\u5de5\u5177**\uff0c\u800c\u975e\u624b\u52a8\u6307\u5b9a\uff1a\n\n```\n\u8bf7\u5148\u901a\u8fc7 get_tool_usage_guide \u4e86\u89e3 context-mcp \u63d0\u4f9b\u7684\u6240\u6709\u5de5\u5177\u53ca\u5176\u7528\u9014\u3002\n\u7136\u540e\u6839\u636e\u6211\u7684\u9700\u6c42\uff0c\u81ea\u4e3b\u9009\u62e9\u6700\u5408\u9002\u7684\u5de5\u5177\u7ec4\u5408\u6765\u5b8c\u6210\u4efb\u52a1\u3002\n\n\u6211\u7684\u9700\u6c42\uff1a[\u5728\u6b64\u63cf\u8ff0\u4f60\u7684\u5177\u4f53\u9700\u6c42]\n```\n\n**\u8fd9\u6837\u505a\u7684\u4f18\u52bf\uff1a**\n\n- \u2705 **Agent \u81ea\u4e3b\u51b3\u7b56**\uff1a\u7531 AI \u5224\u65ad\u7528\u54ea\u4e2a\u5de5\u5177\u6700\u9ad8\u6548\n- \u2705 **\u5de5\u5177\u7ec4\u5408\u4f18\u5316**\uff1a\u81ea\u52a8\u4e32\u8054\u591a\u4e2a\u5de5\u5177\u5b8c\u6210\u590d\u6742\u4efb\u52a1\n- \u2705 **\u9002\u5e94\u6027\u5f3a**\uff1a\u5373\u4f7f\u5de5\u5177\u5347\u7ea7\u6216\u65b0\u589e\uff0c\u65e0\u9700\u4fee\u6539 Prompt\n\n---\n\n## \u6838\u5fc3\u80fd\u529b\n\nContext MCP \u63d0\u4f9b **11 \u4e2a MCP \u5de5\u5177**\uff0c\u8ba9 AI Agent \u901a\u8fc7\u53ea\u8bfb\u65b9\u5f0f\u6df1\u5165\u5206\u6790\u4efb\u4f55\u9879\u76ee\u7684\u4ee3\u7801\u5e93\u3002\n\n> **\u4f7f\u7528\u573a\u666f\u793a\u4f8b**\uff1a\u5047\u8bbe\u4f60\u5df2\u914d\u7f6e `PROJECT_ROOT=/path/to/my-web-app`\uff0c\u4ee5\u4e0b\u662f\u5b9e\u9645\u4f7f\u7528\u65b9\u5f0f\u3002\n\n### \ud83d\udcc1 \u5bfc\u822a\u5de5\u5177\uff083 \u4e2a\uff09\n\n- **`list_directory`** - \u5217\u51fa\u76ee\u5f55\u5185\u5bb9\uff0c\u652f\u6301\u6392\u5e8f\u548c\u9650\u5236\u6570\u91cf\n\n - **\u573a\u666f**\uff1a\u521d\u6b21\u63a5\u89e6\u9879\u76ee\uff0c\u60f3\u4e86\u89e3\u6574\u4f53\u7ed3\u6784\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u5217\u51fa\u8fd9\u4e2a Web \u9879\u76ee\u7684\u6839\u76ee\u5f55\u6587\u4ef6\"\n \ud83e\udd16 [\u4f7f\u7528 list_directory] \u663e\u793a\uff1apackage.json, src/, public/, README.md...\n ```\n\n- **`show_tree`** - \u4ee5\u6811\u72b6\u7ed3\u6784\u5c55\u793a\u76ee\u5f55\u5c42\u6b21\uff0c\u652f\u6301\u6df1\u5ea6\u9650\u5236\n\n - **\u573a\u666f**\uff1a\u53ef\u89c6\u5316\u9879\u76ee\u67b6\u6784\uff0c\u751f\u6210\u6587\u6863\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u663e\u793a src/ \u76ee\u5f55\u7684\u5b8c\u6574\u7ed3\u6784\uff0c\u6df1\u5ea63\u5c42\"\n \ud83e\udd16 [\u4f7f\u7528 show_tree] \u5c55\u793a\u6811\u72b6\u56fe\uff0c\u5feb\u901f\u4e86\u89e3\u6a21\u5757\u5212\u5206\n ```\n\n- **`read_project_context`** - \u8bfb\u53d6\u9879\u76ee\u7684 AI \u4e0a\u4e0b\u6587\u6587\u4ef6\uff08AGENTS.md, CLAUDE.md\uff09\n - **\u573a\u666f**\uff1a\u81ea\u52a8\u53d1\u73b0\u9879\u76ee\u7684 AI \u534f\u4f5c\u89c4\u8303\u548c\u7f16\u7801\u7ea6\u5b9a\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u8fd9\u4e2a\u9879\u76ee\u6709\u914d\u7f6e AI \u534f\u4f5c\u89c4\u8303\u5417\uff1f\"\n \ud83e\udd16 [\u4f7f\u7528 read_project_context] \u53d1\u73b0 CLAUDE.md\uff0c\u5305\u542b\u4ee3\u7801\u98ce\u683c\u3001\u6d4b\u8bd5\u8981\u6c42...\n ```\n\n### \ud83d\udd0d \u641c\u7d22\u5de5\u5177\uff084 \u4e2a\uff09\n\n- **`search_in_file`** - \u5728\u5355\u4e2a\u6587\u4ef6\u4e2d\u641c\u7d22\u6587\u672c\u6216\u6b63\u5219\u8868\u8fbe\u5f0f\n\n - **\u573a\u666f**\uff1a\u5df2\u77e5\u6587\u4ef6\uff0c\u9700\u8981\u5b9a\u4f4d\u7279\u5b9a\u4ee3\u7801\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u5728 src/config/database.js \u4e2d\u641c\u7d22\u6570\u636e\u5e93\u8fde\u63a5\u914d\u7f6e\"\n \ud83e\udd16 [\u4f7f\u7528 search_in_file] \u627e\u5230\u7b2c23\u884c\u7684 DB_HOST \u914d\u7f6e\n ```\n\n- **`search_in_files`** - \u8de8\u591a\u4e2a\u6587\u4ef6\u9012\u5f52\u641c\u7d22\uff0c\u652f\u6301\u6b63\u5219\u8868\u8fbe\u5f0f\u548c\u6392\u9664\u6a21\u5f0f\n\n - **\u573a\u666f**\uff1a\u4ee3\u7801\u5ba1\u8ba1\u3001\u8ffd\u8e2a API \u8c03\u7528\u3001\u67e5\u627e\u6280\u672f\u503a\u52a1\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n\n ```\n \ud83d\udc64 \"\u5728\u6574\u4e2a\u9879\u76ee\u4e2d\u641c\u7d22\u6240\u6709 TODO \u6ce8\u91ca\uff0c\u6392\u9664 node_modules\"\n \ud83e\udd16 [\u4f7f\u7528 search_in_files] \u53d1\u73b015\u5904\u5f85\u529e\u4e8b\u9879\uff0c\u5206\u5e03\u57288\u4e2a\u6587\u4ef6\u4e2d\n\n \ud83d\udc64 \"\u67e5\u627e\u9879\u76ee\u4e2d\u6240\u6709\u8c03\u7528 fetch() \u7684\u5730\u65b9\"\n \ud83e\udd16 [\u4f7f\u7528 search_in_files] \u5b9a\u4f4d\u523023\u5904 API \u8c03\u7528\u70b9\n ```\n\n- **`find_files_by_name`** - \u6309\u6587\u4ef6\u540d\u67e5\u627e\uff08\u652f\u6301\u901a\u914d\u7b26\uff09\n\n - **\u573a\u666f**\uff1a\u5feb\u901f\u5b9a\u4f4d\u914d\u7f6e\u6587\u4ef6\u3001\u6d4b\u8bd5\u6587\u4ef6\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n\n ```\n \ud83d\udc64 \"\u627e\u51fa\u8fd9\u4e2a React \u9879\u76ee\u4e2d\u6240\u6709\u7684\u6d4b\u8bd5\u6587\u4ef6\"\n \ud83e\udd16 [\u4f7f\u7528 find_files_by_name \"*.test.jsx\"] \u627e\u523032\u4e2a\u6d4b\u8bd5\u6587\u4ef6\n\n \ud83d\udc64 \"\u9879\u76ee\u91cc\u6709\u51e0\u4e2a config.json \u6587\u4ef6\uff1f\"\n \ud83e\udd16 [\u4f7f\u7528 find_files_by_name] \u53d1\u73b03\u4e2a\uff1a\u6839\u76ee\u5f55\u3001src/config\u3001tests/\n ```\n\n- **`find_recently_modified_files`** - \u6309\u6700\u8fd1\u4fee\u6539\u65f6\u95f4\u67e5\u627e\u6587\u4ef6\n - **\u573a\u666f**\uff1a\u4e86\u89e3\u9879\u76ee\u6700\u65b0\u8fdb\u5c55\u3001\u5feb\u901f\u5b9a\u4f4d\u6d3b\u8dc3\u4ee3\u7801\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u8fd9\u4e2a\u9879\u76ee\u6700\u8fd1\u4e00\u5468\u6539\u4e86\u54ea\u4e9b\u6587\u4ef6\uff1f\"\n \ud83e\udd16 [\u4f7f\u7528 find_recently_modified_files] \u663e\u793a12\u4e2a\u6587\u4ef6\uff0c\u4e3b\u8981\u96c6\u4e2d\u5728 auth \u6a21\u5757\n ```\n\n### \ud83d\udcd6 \u8bfb\u53d6\u5de5\u5177\uff084 \u4e2a\uff09\n\n- **`read_entire_file`** - \u8bfb\u53d6\u5b8c\u6574\u6587\u4ef6\u5185\u5bb9\n\n - **\u573a\u666f**\uff1a\u7406\u89e3\u6838\u5fc3\u903b\u8f91\u3001\u5206\u6790\u914d\u7f6e\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u8bfb\u53d6\u8fd9\u4e2a\u9879\u76ee\u7684 package.json\uff0c\u544a\u8bc9\u6211\u7528\u4e86\u54ea\u4e9b\u4e3b\u8981\u4f9d\u8d56\"\n \ud83e\udd16 [\u4f7f\u7528 read_entire_file] \u5206\u6790\u4f9d\u8d56\uff1aReact 18, Express 4.x, MongoDB...\n ```\n\n- **`read_file_lines`** - \u8bfb\u53d6\u6587\u4ef6\u7684\u6307\u5b9a\u884c\u8303\u56f4\n\n - **\u573a\u666f**\uff1a\u7cbe\u786e\u67e5\u770b\u51fd\u6570\u5b9e\u73b0\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"src/utils/auth.js \u7684\u7b2c 50-80 \u884c\u662f\u4ec0\u4e48\u903b\u8f91\uff1f\"\n \ud83e\udd16 [\u4f7f\u7528 read_file_lines] \u8fd9\u662f JWT token \u9a8c\u8bc1\u51fd\u6570...\n ```\n\n- **`read_file_tail`** - \u8bfb\u53d6\u6587\u4ef6\u672b\u5c3e N \u884c\n\n - **\u573a\u666f**\uff1a\u67e5\u770b\u65e5\u5fd7\u3001\u68c0\u67e5\u6587\u4ef6\u6700\u65b0\u5185\u5bb9\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u770b\u770b CHANGELOG.md \u7684\u6700\u540e20\u884c\uff0c\u4e86\u89e3\u6700\u65b0\u7248\u672c\u7684\u6539\u52a8\"\n \ud83e\udd16 [\u4f7f\u7528 read_file_tail] \u6700\u65b0\u7248\u672c v2.1.0 \u589e\u52a0\u4e86 OAuth \u652f\u6301...\n ```\n\n- **`read_files`** - \u6279\u91cf\u8bfb\u53d6\u591a\u4e2a\u6587\u4ef6\n - **\u573a\u666f**\uff1a\u5bf9\u6bd4\u5206\u6790\u3001\u751f\u6210\u62a5\u544a\n - **\u5bf9\u8bdd\u793a\u4f8b**\uff1a\n ```\n \ud83d\udc64 \"\u540c\u65f6\u8bfb\u53d6\u524d\u7aef\u548c\u540e\u7aef\u7684\u914d\u7f6e\u6587\u4ef6\uff0c\u5bf9\u6bd4\u73af\u5883\u53d8\u91cf\u8bbe\u7f6e\"\n \ud83e\udd16 [\u4f7f\u7528 read_files] \u8bfb\u53d6 client/.env \u548c server/.env\uff0c\u53d1\u73b0\u4e0d\u4e00\u81f4...\n ```\n\n> \ud83d\udca1 **\u63d0\u793a**\uff1a\u6240\u6709\u5de5\u5177\u90fd\u7ecf\u8fc7\u5b89\u5168\u52a0\u56fa\uff0c\u53ea\u652f\u6301\u53ea\u8bfb\u64cd\u4f5c\uff0c\u8def\u5f84\u4e25\u683c\u9650\u5236\u5728\u914d\u7f6e\u7684 PROJECT_ROOT \u5185\u3002\n\n## \u6027\u80fd\u4f18\u5316\n\nContext MCP \u4f1a\u4f18\u5148\u4f7f\u7528\u9ad8\u6027\u80fd\u7684\u547d\u4ee4\u884c\u5de5\u5177,\u5f53\u8fd9\u4e9b\u5de5\u5177\u4e0d\u53ef\u7528\u65f6\u81ea\u52a8\u964d\u7ea7\u5230\u6807\u51c6\u5de5\u5177\u6216 Python \u5b9e\u73b0,\u786e\u4fdd\u5728\u4efb\u4f55\u73af\u5883\u4e0b\u90fd\u80fd\u6b63\u5e38\u5de5\u4f5c\u3002\n\n### \u6027\u80fd\u5bf9\u6bd4\n\n**\u57fa\u51c6\u6d4b\u8bd5\u73af\u5883**: \u4e2d\u578b\u9879\u76ee (1000-10000 \u6587\u4ef6, 10MB-100MB)\n\n| \u64cd\u4f5c | \u9ad8\u6027\u80fd\u5de5\u5177 | \u6807\u51c6\u5de5\u5177 | Python \u5b9e\u73b0 | \u52a0\u901f\u6bd4 |\n| ------------ | ----------------- | ----------- | ------------- | --------- |\n| \u6587\u4ef6\u5185\u5bb9\u641c\u7d22 | **ripgrep** 180ms | grep 2400ms | Python 4200ms | **13.3x** |\n| \u6587\u4ef6\u540d\u67e5\u627e | **fd** 50ms | find 450ms | Python 680ms | **9.0x** |\n\n### \u63a8\u8350\u5de5\u5177\u5b89\u88c5\n\n\u4e3a\u83b7\u5f97\u6700\u4f73\u6027\u80fd,\u5efa\u8bae\u5b89\u88c5\u4ee5\u4e0b\u9ad8\u6027\u80fd\u5de5\u5177:\n\n#### ripgrep (rg) - \u9ad8\u6027\u80fd\u641c\u7d22\n\n**Windows**:\n\n```powershell\n# Chocolatey\nchoco install ripgrep\n\n# Scoop\nscoop install ripgrep\n```\n\n**Linux**:\n\n```bash\n# Ubuntu/Debian\nsudo apt install ripgrep\n\n# Fedora\nsudo dnf install ripgrep\n```\n\n**macOS**:\n\n```bash\nbrew install ripgrep\n```\n\n**\u5b98\u65b9\u4e0b\u8f7d**: https://github.com/BurntSushi/ripgrep#installation\n\n#### fd - \u9ad8\u6027\u80fd\u6587\u4ef6\u67e5\u627e\n\n**Windows**:\n\n```powershell\n# Chocolatey\nchoco install fd\n\n# Scoop\nscoop install fd\n```\n\n**Linux**:\n\n```bash\n# Ubuntu/Debian (\u9700\u8981 Ubuntu 19.04+ \u6216\u624b\u52a8\u5b89\u88c5)\nsudo apt install fd-find\n\n# Fedora\nsudo dnf install fd-find\n```\n\n**macOS**:\n\n```bash\nbrew install fd\n```\n\n**\u5b98\u65b9\u4e0b\u8f7d**: https://github.com/sharkdp/fd#installation\n\n> \ud83d\udcdd **\u8bf4\u660e**: \u8fd9\u4e9b\u5de5\u5177\u662f\u53ef\u9009\u7684\u3002Context MCP \u5728\u6ca1\u6709\u8fd9\u4e9b\u5de5\u5177\u7684\u73af\u5883\u4e0b\u4f1a\u81ea\u52a8\u964d\u7ea7\u5230\u7cfb\u7edf\u81ea\u5e26\u7684 grep/find \u6216 Python \u5b9e\u73b0,\u529f\u80fd\u5b8c\u5168\u4e0d\u53d7\u5f71\u54cd,\u53ea\u662f\u6027\u80fd\u4f1a\u6709\u6240\u964d\u4f4e\u3002\u670d\u52a1\u542f\u52a8\u65f6\u4f1a\u5728\u65e5\u5fd7\u4e2d\u663e\u793a\u5de5\u5177\u68c0\u6d4b\u7ed3\u679c\u3002\n\n## \u5b89\u5168\u6027\n\n- **\u53ea\u8bfb\u64cd\u4f5c**\uff1a\u4e0d\u63d0\u4f9b\u5199\u5165\u3001\u4fee\u6539\u6216\u5220\u9664\u529f\u80fd\n- **\u8def\u5f84\u9a8c\u8bc1**\uff1a\u6240\u6709\u8def\u5f84\u4e25\u683c\u9650\u5236\u5728\u914d\u7f6e\u7684 PROJECT_ROOT \u5185\n- **\u4e8c\u8fdb\u5236\u6587\u4ef6\u4fdd\u62a4**\uff1a\u62d2\u7edd\u5c06\u4e8c\u8fdb\u5236\u6587\u4ef6\u4f5c\u4e3a\u6587\u672c\u8bfb\u53d6\n- **\u6743\u9650\u5904\u7406**\uff1a\u4f18\u96c5\u5904\u7406\u6743\u9650\u9519\u8bef\n\n## \u5e38\u89c1\u95ee\u9898\n\n## \u5f00\u53d1\u6307\u5357\n\n**\u8d21\u732e\u8005\u5feb\u901f\u5f00\u59cb\uff1a**\n\n```bash\n# \u514b\u9686\u5e76\u8bbe\u7f6e\ngit clone https://github.com/geq1fan/context-mcp.git\ncd context-mcp\nuv sync\n\n# \u8fd0\u884c\u6d4b\u8bd5\nPROJECT_ROOT=$(pwd) uv run pytest\n\n# \u8fd0\u884c\u6d4b\u8bd5\u5e76\u751f\u6210\u8986\u76d6\u7387\u62a5\u544a\nPROJECT_ROOT=$(pwd) uv run pytest --cov=context_mcp\n```\n\n**\u6d4b\u8bd5\u8986\u76d6\u7387**\uff1a237 \u4e2a\u6d4b\u8bd5\uff08232 \u901a\u8fc7 + 5 \u8df3\u8fc7\uff09\uff0c\u8986\u76d6\u7387 78%\uff08\u8fd0\u884c `PROJECT_ROOT=$(pwd) python -m pytest --cov=context_mcp`\uff09\n\n## \u6587\u6863\n\n- **[README.md](README.md)** - \u672c\u6587\u4ef6\uff0c\u5feb\u901f\u5f00\u59cb\u548c\u6982\u89c8\n- **[SECURITY.md](SECURITY.md)** - \u5b89\u5168\u653f\u7b56\u548c\u6f0f\u6d1e\u62a5\u544a\n- **[CHANGELOG.md](CHANGELOG.md)** - \u7248\u672c\u5386\u53f2\u548c\u53d8\u66f4\u8bb0\u5f55\n- **[LICENSE](LICENSE)** - MIT \u8bb8\u53ef\u8bc1\u6587\u672c\n\n## \u7cfb\u7edf\u8981\u6c42\n\n- Python 3.11 \u6216\u66f4\u9ad8\u7248\u672c\n\n## \u5f00\u6e90\u8bb8\u53ef\n\nMIT License - \u5b8c\u6574\u5185\u5bb9\u8bf7\u67e5\u770b [LICENSE](LICENSE) \u6587\u4ef6\u3002\n\n- \u2705 \u5141\u8bb8\u5546\u4e1a\u4f7f\u7528\u3001\u4fee\u6539\u548c\u5206\u53d1\n- \u26a0\ufe0f \u4e0d\u63d0\u4f9b\u4efb\u4f55\u62c5\u4fdd\n\n## \u53c2\u4e0e\u8d21\u732e\n\n\u6b22\u8fce\u8d21\u732e\uff01\ud83c\udf89\n\n**\u5feb\u901f\u8d21\u732e\u6307\u5357\uff1a**\n\n1. Fork \u672c\u4ed3\u5e93\n2. \u521b\u5efa\u7279\u6027\u5206\u652f\uff08`git checkout -b feature/amazing-feature`\uff09\n3. \u63d0\u4ea4\u4f60\u7684\u4fee\u6539\u5e76\u6dfb\u52a0\u6d4b\u8bd5\n4. \u786e\u4fdd\u6240\u6709\u6d4b\u8bd5\u901a\u8fc7\uff08`PROJECT_ROOT=$(pwd) uv run pytest`\uff09\n5. \u63d0\u4ea4 Pull Request\n\n## \u652f\u6301\u4e0e\u793e\u533a\n\n- **\u95ee\u9898\u53cd\u9988**\uff1a[GitHub Issues](https://github.com/geq1fan/context-mcp/issues)\n- **\u8ba8\u8bba\u4ea4\u6d41**\uff1a[GitHub Discussions](https://github.com/geq1fan/context-mcp/discussions)\n- **\u5b89\u5168\u6f0f\u6d1e**\uff1a\u53c2\u8003 [SECURITY.md](SECURITY.md) \u62a5\u544a\u5b89\u5168\u95ee\u9898\n\n---\n\n**\u6784\u5efa\u5de5\u5177** [FastMCP](https://github.com/jlowin/fastmcp) \u2022 **\u9002\u914d\u5e73\u53f0** [Claude Desktop](https://claude.ai/desktop) \u2022 **\u57fa\u4e8e\u534f\u8bae** [MCP](https://modelcontextprotocol.io/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for project context integration - provides read-only filesystem operations for AI agents",
"version": "0.2.4",
"project_urls": {
"Bug Tracker": "https://github.com/geq1fan/context-mcp/issues",
"Changelog": "https://github.com/geq1fan/context-mcp/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/geq1fan/context-mcp#readme",
"Homepage": "https://github.com/geq1fan/context-mcp",
"Repository": "https://github.com/geq1fan/context-mcp"
},
"split_keywords": [
"agent",
" ai",
" claude",
" code-analysis",
" context-integration",
" fastmcp",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18ac67cafc6e71f10f2505047c48ed3e8e1177033e988b07ac50a23dd13ecbe8",
"md5": "a981af474dc9a2c3bcca2a555b0d1b0a",
"sha256": "c3b3a5f30201e5e6c00055a4143cbe41ca969d389e492a2132cd003a208b02c7"
},
"downloads": -1,
"filename": "context_mcp-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a981af474dc9a2c3bcca2a555b0d1b0a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32129,
"upload_time": "2025-10-28T14:39:44",
"upload_time_iso_8601": "2025-10-28T14:39:44.402242Z",
"url": "https://files.pythonhosted.org/packages/18/ac/67cafc6e71f10f2505047c48ed3e8e1177033e988b07ac50a23dd13ecbe8/context_mcp-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "61f53662a1f0800045fa7807f023614ce5cbd5b36c4f6f5516268f52b5d5cd00",
"md5": "f0a9a1510d967700beb938e109432797",
"sha256": "0236435ab486cbe4eec7f190e41a2d3fe6b52acc1bb14d2736dbc493707a91bd"
},
"downloads": -1,
"filename": "context_mcp-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "f0a9a1510d967700beb938e109432797",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 202590,
"upload_time": "2025-10-28T14:39:46",
"upload_time_iso_8601": "2025-10-28T14:39:46.031931Z",
"url": "https://files.pythonhosted.org/packages/61/f5/3662a1f0800045fa7807f023614ce5cbd5b36c4f6f5516268f52b5d5cd00/context_mcp-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 14:39:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geq1fan",
"github_project": "context-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "context-mcp"
}
JSON
