项目简介

'py-mcp-collection' 仓库是一个包含多个基于 Python 实现的 Model Context Protocol (MCP) 服务器的集合，主要用于增强 AI 编程助手的能力。这些服务器以标准化的方式提供特定领域的上下文信息和可调用工具。

当前仓库包含以下主要 MCP 服务器实现：

Filesystem Operations (文件系统操作): 提供对本地文件系统的访问、搜索和内容提取能力。
Local References (本地参考): 允许将项目中的本地文档（如指南、最佳实践）作为结构化参考提供给 AI。
MCP Oops: 一个代理服务器，用于修改或组合其他 MCP 服务器的行为。
Doc Store Vector Search (文档存储向量搜索) (开发中): 旨在提供文档的向量存储和搜索功能。
MCP Utils: 一个供 MCP 服务器使用的工具库。

本文档主要介绍 Filesystem Operations 和 Local References 这两个已可用的服务器。

主要功能点

文件系统操作:
- 浏览目录结构。
- 读取文件内容（包括预览和全文）。
- 按名称或内容搜索文件。
- 获取文件元数据（大小、类型、修改日期等）。
- 提供基础的代码和文本内容摘要（开发中）。
本地参考:
- 根据配置路径暴露本地文件夹作为特定类型的参考（如 "最佳实践", "操作指南"）。
- 根据参考类型和名称检索特定文档内容。
- 提供所有可用参考类型的预览和条目列表。
MCP Oops:
- 作为其他 MCP 服务器的代理。
- 限制工具响应大小。
- 在单一端口上合并多个 MCP 服务器。
- 修改工具名称、描述或参数。
- 为工具调用添加前置/后置钩子。

安装步骤

该仓库使用 Python 实现，依赖 'pip' 进行包管理。

克隆仓库: 首先，使用 git 克隆整个仓库到本地。

git clone https://github.com/strawgate/py-mcp-collection.git
cd py-mcp-collection

安装依赖: 进入仓库目录后，可以针对某个具体的 MCP 服务器目录安装依赖。例如，安装 Filesystem Operations 服务器的依赖：

cd filesystem-operations-mcp
pip install .

同样地，安装 Local References 服务器的依赖：

cd ../local-references-mcp
pip install .

安装 MCP Oops 服务器的依赖：

cd ../mcp-oops
pip install .

请根据需要运行的服务器安装对应的依赖。

服务器配置

MCP 服务器通常通过标准输入/输出 (stdio) 与 MCP 客户端通信。MCP 客户端需要知道如何启动服务器进程。以下是 Filesystem Operations 和 Local References 服务器的典型 MCP 客户端配置（JSON 格式），用于启动服务器并与之建立 stdio 连接：

Filesystem Operations 服务器配置示例:

{
  "server name": "local_filesystem",
  "command": "python",
  "args": [
    "-m",
    "filesystem_operations_mcp.main",
    "--root-dir", "/path/to/your/project", // 指定服务器可访问的文件系统根目录
    "--mcp-transport", "stdio" // 指定使用 stdio 传输协议
  ]
}

'server name': 客户端用于标识此服务器的名称。
'command': 启动服务器的可执行命令，这里是 'python'。
'args': 传递给命令的参数列表。
- '-m filesystem_operations_mcp.main': 运行 Filesystem Operations 服务器的主模块。
- '--root-dir /path/to/your/project': 重要参数，指定该 MCP 服务器被允许操作的文件系统根目录。'/path/to/your/project' 应替换为实际路径。
- '--mcp-transport stdio': 指定服务器使用 stdio 协议与客户端通信，这是 MCP 客户端常用的连接方式。

Local References 服务器配置示例:

{
  "server name": "local_references",
  "command": "python",
  "args": [
    "-m",
    "local_references_mcp.main",
    "--reference", "Best Practices:/path/to/best/practices/docs", // 指定参考类型和路径，可重复多次
    "--reference", "How To:/path/to/how/to/guides",
    "--preview-size", "1000" // 指定预览时截断的字符数
  ]
}

'server name': 客户端用于标识此服务器的名称。
'command': 启动服务器的可执行命令，这里是 'python'。
'args': 传递给命令的参数列表。
- '-m local_references_mcp.main': 运行 Local References 服务器的主模块。
- '--reference "类型:路径"': 重要参数，定义一个本地参考源。'类型' 是参考的名称，'路径' 是包含 Markdown 文档的本地文件夹路径（通常包含一个 'README.md' 作为描述）。可以多次使用 '--reference' 参数来添加多个参考源。
- '--preview-size 1000': 指定在预览参考时每个条目显示的最大字符数。

MCP Oops 服务器配置示例:

MCP Oops 作为代理，其配置会复杂一些，因为它需要知道如何启动其代理的下游服务器，以及应用哪些覆盖规则。以下是 MCP Oops 客户端配置，其中 'config-file' 指定了一个 YAML 或 JSON 文件，该文件描述了下游 MCP 服务器和要应用的覆盖规则。

{
  "server name": "mcp_oops_proxy",
  "command": "python",
  "args": [
    "-m",
    "mcp_oops.main",
    "config", // 使用 config 命令模式
    "/path/to/mcp_oops_config.yaml", // 指向 MCP Oops 配置文件
    "--oops-transport", "stdio", // 指定 MCP Oops 使用 stdio 传输协议
    "--limit-response-size", "500000" // 应用响应大小限制 (bytes)
  ]
}

MCP Oops 的 '/path/to/mcp_oops_config.yaml' 文件示例可能如下（详细结构请参考 MCP Oops 文档）：

mcpServers:
  filesystem:
    command: python
    args:
      - -m
      - filesystem_operations_mcp.main
      - --root-dir
      - /path/to/your/project
      - --mcp-transport
      - stdio # 这里指定下游服务器也用 stdio，以便 MCP Oops 代理
    tools: # 工具覆盖规则，可选
      get_files:
        name: list_project_files
        description: "List files in the project directory"

客户端需要配置启动 MCP Oops 本身的命令和参数，同时 MCP Oops 自身需要一个额外的配置文件来描述它要代理哪些服务器以及如何代理。

基本使用方法

一旦在支持 MCP 的客户端中配置并成功启动了这些服务器，客户端（通常是 AI 编程助手）就可以发现服务器暴露的工具（Tools）并按需调用它们。

例如，对于 Filesystem Operations 服务器，客户端可以调用类似 'get_structure'（获取目录结构）、'get_files'（获取特定文件内容）或 'find_files'（查找文件）的工具，并传递相应的参数（如路径、 glob 模式）。

对于 Local References 服务器，客户端可以调用 'preview_references' 工具来获取所有参考类型的列表和预览，或者调用 'get_reference' 工具，指定参考类型和条目名称来获取具体文档的全文内容。

AI 助手会根据用户的请求或当前任务，智能地选择合适的 MCP 服务器和工具进行调用，以获取必要的信息或执行相关操作。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息