Moatless MCP Server

一个基于模型上下文协议 (MCP) 的高级代码分析和编辑服务器，支持基于向量嵌入的语义搜索功能。该服务器为 AI 助手提供了通过标准化接口执行复杂代码操作的能力。

本服务器是一个MCP服务器的实现。MCP是一个开放协议，旨在成为语言模型（LLM）与外部工具和数据源之间的标准中间件。它允许像IDE或聊天应用这样的客户端（MCP客户端）安全、动态地与服务器提供的能力（如文件系统访问、代码分析）进行交互。

当一个MCP客户端（如Claude Desktop或cline）连接到本服务器时，其交互遵循以下流程：

+------------------+ 1. Request (e.g., call_tool) +-----------------------+ | MCP Client | -----------------------------------> | MCP Server | | (IDE, cline etc.)| | (This Project) | +------------------+ 6. Response (JSON-RPC) +-----------+-----------+ ^ <----------------------------------- | 2. Dispatch | | | v | +-----------------------+ | | Tool Registry | | +-----------+-----------+ | | 3. Execute Tool | | | v | +-----------------------+ | | Specific Tool | | | (e.g., ReadFileTool) | | +-----------+-----------+ | | 4. Access Data | | | +----------------------------------------------------+ | | v v +-----------------------+ 5. Return Data/Result +-----------------------+ | Workspace | <----------------------------- | Workspace Adapter | | (File System, .git) | | (Manages Project State) | +-----------------------+ +-----------------------+

- 请求(Request): 客户端向服务器发送一个JSON-RPC请求，例如tool_run，要求执行一个名为read_file的工具。
- 分发(Dispatch):server.py中的MCP服务器核心接收请求，并将其分派给ToolRegistry。
- 执行(Execute):ToolRegistry找到名为read_file的已注册工具实例，并调用其execute方法。
- 数据访问(Access Data): 工具通过WorkspaceAdapter请求访问项目文件。
- 返回结果(Return Data):WorkspaceAdapter从文件系统读取数据并返回给工具。工具将结果包装成ToolResult对象。
- 响应(Response): 服务器核心将ToolResult格式化为JSON-RPC响应，并将其发送回客户端。

- 职责: 作为服务器的主入口，监听和响应MCP客户端的连接。
- 实现: 使用mcp.server库来处理底层的JSON-RPC通信。它定义了list_tools和call_tool等协议处理器，并将具体的逻辑委托给ToolRegistry。

- 职责: 负责工具的生命周期管理。它在启动时实例化所有可用的工具，并将它们存储在一个字典中以便快速访问。
- 实现:ToolRegistry类包含一个_register_default_tools方法，用于集中注册所有工具。当execute_tool被调用时，它会查找并执行相应的工具。

Workspace Adapter (adapters/workspace.py):

- 职责: 作为文件系统和项目状态的抽象层。所有对项目文件的��、写、搜索操作都必须通过这个适配器进行。
- 实现:WorkspaceAdapter类提供了对文件、Git仓库和Moatless语义索引的访问接口，同时强制执行安全策略（如文件类型和路径限制）。

- 职责: 实现具体的业务逻辑单元。每个工具都是一个独立的类，负责一项特定的任务，如读写文件、代码搜索或运行测试。
- 实现: 所有工具都继承自MCPTool基类(tools/base.py)，并实现execute方法。它们通过构造函数接收WorkspaceAdapter的实例来与项目数据交互。

Vector System & Tree-sitter (vector/,treesitter/):

- 职责: 提供高级代码理解能力。Vector System负责将代码转换为向量并进行语义搜索。Tree-sitter用于精确解析代码的语法结构（AST）。
- 实现: 这些模块被高级工具（如SemanticSearchTool和FindClassTool）所使用，以提供比简单文本匹配更强大的功能。

- 向量嵌入: 使用 Jina AI 1024 维嵌入 (推荐) 或 OpenAI 嵌入 (已弃用)。
- 按需构建: 向量索引仅在需要时通过build_vector_index工具构建，避免不必要的启动延迟。
- 代码分割: 基于 Moatless 库的智能代码块分割。
- 相似性搜索: 使用 FAISS 向量数据库实现高效搜索。

- 白名单策略: 默认允许访问多种常见代码、配置和文档文件类型。
- 智能路径过滤: 仅禁止核心依赖和缓存目录 (node_modules,.venv,__pycache__等)。
- 可配置性: 可以通过Config类轻松调整安全设置。

- 工具基类:MCPTool提供了一个清晰的接口，用于创建新的自定义工具。
- 集中注册:ToolRegistry使得添加和管理新工具变得简单。

{ "tool": "read_file", "arguments": { "file_path": "src/moatless_mcp/server.py", "start_line": 1, "end_line": 10 } }

{ "tool": "semantic_search", "arguments": { "query": "user authentication and login validation", "max_results": 5 } }

{ "tool": "find_class", "arguments": { "class_name": "ToolRegistry", "file_pattern": "/registry.py" } }

关于如何运行此服务器、进行部署以及如何开发和添加新工具的详细说明，请参阅README_deploy.md。

- MCP 规范- 官方 MCP 协议规范
- Moatless Tools- 底层语义搜索库
- Tree-sitter- 代码解析器
- FAISS**- 向量相似性搜索

AI-to-AI code review platform — Claude, Codex, and Gemini cross-check each other via MCP, REST API, and CLI for consensus-based results.