Moatless MCP Server

Moatless MCP Server

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

核心架构：模型上下文协议 (MCP)

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

架构流程

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

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

组件详解

• Server Core (server.py):
  • 职责: 作为服务器的主入口，监听和响应MCP客户端的连接。
  • 实现: 使用mcp.server库来处理底层的JSON-RPC通信。它定义了list_tools和call_tool等协议处理器，并将具体的逻辑委托给ToolRegistry。
• Tool Registry (tools/registry.py):
  • 职责: 负责工具的生命周期管理。它在启动时实例化所有可用的工具，并将它们存储在一个字典中以便快速访问。
  • 实现: ToolRegistry类包含一个_register_default_tools方法，用于集中注册所有工具。当execute_tool被调用时，它会查找并执行相应的工具。
• Workspace Adapter (adapters/workspace.py):
  • 职责: 作为文件系统和项目状态的抽象层。所有对项目文件的��、写、搜索操作都必须通过这个适配器进行。
  • 实现: WorkspaceAdapter类提供了对文件、Git仓库和Moatless语义索引的访问接口，同时强制执行安全策略（如文件类型和路径限制）。
• Tools (tools/*.py):
  • 职责: 实现具体的业务逻辑单元。每个工具都是一个独立的类，负责一项特定的任务，如读写文件、代码搜索或运行测试。
  • 实现: 所有工具都继承自MCPTool基类(tools/base.py)，并实现execute方法。它们通过构造函数接收WorkspaceAdapter的实例来与项目数据交互。
• Vector System & Tree-sitter (vector/, treesitter/):
  • 职责: 提供高级代码理解能力。Vector System负责将代码转换为向量并进行语义搜索。Tree-sitter用于精确解析代码的语法结构（AST）。
  • 实现: 这些模块被高级工具（如SemanticSearchTool和FindClassTool）所使用，以提供比简单文本匹配更强大的功能。

关键技术特性

1. 语义搜索实现

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

2. 灵活的安全模型

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

3. 模块化和可扩展的工具系统

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

使用示例

基础文件操作

语义搜索

代码结构分析

部署与开发

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

相关文档

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