AI导哈

MCP项目信息传输服务

一个基于FastMCP 2.x的HTTP传输服务，用于通过Docker或本地运行暴露项目信息文件（project_info.md），支持与Claude Desktop等MCP客户端通信。

  • by ziutus
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ziutus/mcp-server

使用说明

项目信息MCP--HTTP传输+Docker设置

此存储库包含一个最小的FastMCP 2.x服务器，它公开了一个资源：文件 project_info.md （担任 text/markdown).

它现在使用FastMCP的内置HTTP传输（没有单独的FastAPI服务器）。服务监听端口 8000 并通过HTTP讲述模型上下文协议。这适用于支持MCP的客户端（例如Claude Desktop、开发工具），而不是通用的REST API。

下面您将找到以下说明：

  • 使用Docker Desktop构建并运行服务器
  • 配置Claude Desktop以在Docker中启动服务器，并通过stdio（MCP命令传输）与其通信

先决条件

  • Docker桌面已安装并正在运行
  • 可选（不带Docker的本地测试）：带Docker的Python 3.13+ fastmcp>=2,<3
  • Claude Desktop（支持MCP）

构建Docker镜像

从项目根目录运行这些命令（其中 Dockerfile 生活）。

docker build -t project-info-mcp:latest .

笔记：

  • 图像使用 python:3.13-slim 并安装 fastmcp>=2,<3.
  • 容器的工作目录是 /app 它会跑 python main.py 默认情况下。

运行容器（手动测试）

MCP服务器在端口8000上通过HTTP运行。您可以交互式运行容器以查看日志：

docker run --rm -it project-info-mcp:latest

如果你想让集装箱服务于你当前的本地 project_info.md （因此编辑会实时反映），以只读方式挂载，并发布端口8000：

# Windows PowerShell (from project root)
docker run --rm -i -p 8000:8000 -v "$PWD/project_info.md:/app/project_info.md:ro" project-info-mcp:latest

# macOS/Linux
docker run --rm -i -p 8000:8000 -v "${PWD}/project_info.md:/app/project_info.md:ro" project-info-mcp:latest

提示（Windows CMD）：替换 $PWD 随着 %CD%.

使用Docker Compose作为服务运行（可选）

docker compose up --build
# stop with
docker compose down

这对于在执行/附加调试时保持容器运行非常有用。Compose文件映射 8000:8000 用于HTTP传输。

使用FastMCP HTTP传输

服务器代码遵循FastMCP HTTP传输模式：

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

在这个存储库中，我们公开了一个资源而不是一个工具。看 main.py 具体实施。使用以下命令在本地启动服务器：

pip install -e .
python main.py
# MCP is listening on http://127.0.0.1:8000

注意：MCP over HTTP不是一个人性化的REST API。使用支持MCP的客户端进行连接。

配置Claude Desktop以使用容器

Claude Desktop可以通过命令传输启动MCP服务器。我们将指出 docker run ... 因此，它按需启动容器，并通过stdio进行通信。

您有两种配置方法。挑一个。

选项A：通过Claude桌面用户界面进行配置

  1. 打开克劳德桌面
  2. 转到“设置”→ 开发者→ 模型上下文协议（MCP）服务器
  3. 添加新的MCP服务器：
    • 姓名： project-info-mcp
    • 命令： docker
    • 论据：
      run --rm -i project-info-mcp:latest
    • 保存

如果你想让服务器读取你的主机 project_info.md，在Arguments中添加绑定挂载（在Windows上引用时要小心）：

run --rm -i 
  -v ${PWD}/project_info.md:/app/project_info.md:ro 
  project-info-mcp:latest

在Windows PowerShell上， ${PWD} 展开到当前目录。在CMD中，使用 %CD%。如果在UI中引用有问题，您可以使用下面的JSON文件方法，其中多参数数组更清晰。

选项B：通过claude_desktop_config json进行配置

在下面的平台路径中创建或编辑配置文件，并在下面添加一个条目 mcpServers.

  • 窗户： %APPDATA%/Claude/claude_desktop_config.json
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux： ~/.config/Claude/claude_desktop_config.json

最小配置（无绑定挂载）：

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "project-info-mcp:latest"
      ]
    }
  }
}

配置绑定挂载以服务于您的本地 project_info.md 只读：

Windows（PowerShell使用 $PWD；对于CMD，请替换为 %CD%):

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${PWD}/project_info.md:/app/project_info.md:ro",
        "project-info-mcp:latest"
      ]
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "project-info-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${PWD}/project_info.md:/app/project_info.md:ro",
        "project-info-mcp:latest"
      ]
    }
  }
}

保存配置后，重新启动Claude Desktop。

在Claude Desktop中验证

  1. 打开或开始新的聊天
  2. 确保MCP服务器 project-info-mcp 出现在工具列表中（取决于UI版本）
  3. 请克劳德列出MCP资源。您应该看到一个URI为的资源：
    • mcp://project-info-mcp/project_info 和 mime_type: text/markdown
  4. 请克劳德阅读 project_info 资源；它应该返回以下内容 project_info.md.

故障排除

  • 找不到Docker命令：确保Docker Desktop已安装并正在运行。
  • Windows上的权限/卷错误：请尝试以管理员身份运行PowerShell，或使用 %CD% （CMD）或完整路径 -v 安装。
  • Claude中没有列出资源：请检查Claude的开发人员设置和日志；确认容器启动（您应该在Claude控制台中看到日志）。尝试手动运行容器以确认其正常工作： docker run --rm -it project-info-mcp:latest.
  • project_info.md 未反映的更改：请验证您是否添加了 -v mount将主机文件绑定到 /app/project_info.md 在容器中。

本地（非Docker）运行

如果你更喜欢在没有Docker的情况下进行本地测试：

pip install -e .
python main.py

Claude Desktop配置（命令传输）将指向 python 带args ["main.py"] 而不是 docker run ....

参考

  • 服务器公开的资源URI： mcp://project-info-mcp/project_info
  • MIME类型： text/markdown
  • 基础图像： python:3.13-slim
  • 主要入口点： python main.py

使用MCP检查器（npx@modelcontextprotocol/Inspector）进行测试

使用官方的MCP检查器来验证和调试服务器。这适用于Docker化服务器或本地Python运行。

先决条件

  • Node.js 18+（包括 npx).从以下位置安装https://nodejs.org如果需要的话。
  • 此仓库中的服务器代码（已设置）。
  • 可选：如果你想运行容器化服务器，可以使用Docker Desktop。

选项A——检查Docker化服务器

  1. 构建映像（从项目根目录开始）：

    docker build -t project-info-mcp:latest .

  2. 启动MCP检查器UI：

    npx -y @modelcontextprotocol/inspector
    • 这将在浏览器中打开检查器（或打印本地URL）。如果浏览器没有自动打开，请从终端复制URL并将其粘贴到浏览器中。

  3. 使用命令（stdio）将检查器连接到服务器：

    • 点击“连接”。
    • 运输：选择“命令”。
    • 命令： docker
    • 参数（无绑定挂载）：
      run --rm -i project-info-mcp:latest
    • 点击“连接”。检查器将启动容器并通过stdio进行通信。

    可选：如果您想实时读取主机文件 project_info.md，添加绑定挂载（调整shell/OS的路径语法）：

    • Windows PowerShell：
      run --rm -i -v ${PWD}/project_info.md:/app/project_info.md:ro project-info-mcp:latest
    • Windows CMD（使用 %CD% 而不是 ${PWD})或macOS/Linux（使用 ${PWD}):
      run --rm -i -v ${PWD}/project_info.md:/app/project_info.md:ro project-info-mcp:latest

  4. 在检查器中练习服务器：

    • 使用资源面板“列出”资源。
    • 你应该看看 mcp://project-info-mcp/project_info 随着 mime_type: text/markdown.
    • 单击/执行“读取资源”操作并选择该URI。检查器将显示以下内容 project_info.md.

选项B——检查本地运行的服务器（无Docker）

  1. 安装deps并在本地运行服务器：

    pip install -e .
python main.py

    （或与 uv: uv run python main.py)

    注意：如果您使用Inspector的命令传输，则不必先启动服务器——Inspector可以为您启动它。请参阅下一步。

  2. 启动MCP检查器UI：

    npx -y @modelcontextprotocol/inspector

  3. 通过命令连接（stdio）：

    • 点击“连接”。
    • 运输：“指挥”。
    • 命令： python
    • 论据：
      main.py
    • 点击“连接”。检查员将启动 python main.py 通过stdio与MCP通话。

  4. 列出并阅读上述资源。

您应该查看/验证的内容

  • 列出的单个资源： mcp://project-info-mcp/project_info.
  • 读取资源会返回您的 project_info.md.
  • 如果 project_info.md 如果缺少，服务器将返回一条简短的markdown消息，要求您创建它。

提示和故障排除（检查员）

  • Docker标志：
    • 使用 -i （交互式标准输入）。不添加 -t 通过Inspector启动时，因为TTY可能会干扰stdio帧。
  • Windows路径/引用：
    • PowerShell使用 ${PWD}；CMD使用 %CD%。如果在Inspector UI中引用很棘手，请先尝试本地（非Docker）路径以确认连接。
  • 如果没有资源出现：
    • 检查检查器的连接日志（左侧/底部面板）是否存在启动错误。
    • 尝试在Inspector之外运行服务器以确保其启动： docker run --rm -it project-info-mcp:latest 或 python main.py.
  • 节点要求：
    • 如果 npx 找不到，请安装Node.js。在公司计算机上，您可能需要配置一个代理 npm.
  • FastMCP CLI（备选）：
    • 如果你有 fastmcp 安装后，它提供了一个开发助手，可以向检查器发送外壳并为您连接代理。示例（语法可能因版本而异）：
      python -m fastmcp dev -- command python main.py
    • 这是可选的；使用 npx @modelcontextprotocol/inspector 直接就足够了。

相关 MCP