AI导哈

TODO MCP服务

一个基于Python实现的TODO MCP服务器，通过HTTP提供添加、列出和删除TODO项的功能，数据存储在本地JSON文件中。

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

使用说明

Claude的TODO MCP服务器（Python）

使用Python实现的简单TODO MCP服务器 mcp SDK。它通过HTTP公开MCP工具，因此Claude web可以添加、列出和删除TODO，并将数据存储在本地JSON文件中。

特性

  • Python MCP服务器 使用 mcp.server.fastmcp.FastMCP
  • 工具:
    • add_todo_item(text: str) –添加到所有
    • list_todo_items() –列出所有TODO
    • remove_todo_item(todo_id: str) –按id删除
  • 存储：磁盘上带有文件锁定的JSON文件(filelock)
  • 运输：可流式传输HTTP /mcp （默认端口8000）
  • 身份验证模式 （目前仅配置）：
    • AUTH_MODE=none –无身份验证（仅限本地）
    • AUTH_MODE=api_key –通过HTTP头的静态API密钥
    • AUTH_MODE=cognito –AWS Cognito JWT验证助手

注意：MCP Python SDK的HTTP传输目前不直接向工具处理程序公开HTTP标头。这 auth.py 模块提供了可重用的功能来验证API密钥和Cognito JWT，您可以在SDK公开挂钩后将其插入到HTTP中间件中，或者通过反向代理在转发到之前终止身份验证 /mcp.

存储库结构

回购根的单一真实来源；没有重复的应用程序代码。

  • 服务器.py –MCP应用程序+HTTP入口点（CORS，可流式传输HTTP）。
  • server_strio.py –克劳德桌面/.mcpb的Stdio入口点。
  • config.py, todo_store.py, auth.py –配置、存储、身份验证助手。
  • mcpb/ –仅捆绑文件： manifest.json, data/.gitkeep。参见 mcpb/README.md.
  • scripts/build-mcpb.sh –建筑 todo-mcp.mcpb 从根+mcpb（从项目根运行）。

1.安装依赖项（本地开发）

从项目根：

python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

2.在本地运行MCP服务器

默认情况下，这将：

  • 倾听 0.0.0.0:8000
  • 将待办事项存储在 ./data/todos.json
  • 使用 AUTH_MODE=api_key （但尚未在HTTP级别强制执行）
export MCP_PORT=8000
export TODO_FILE_PATH=./data/todos.json
export AUTH_MODE=none  # for local testing

python server.py

您应该看到服务器启动时没有错误。

使用MCP检查员进行测试（可选）

在另一个终端中：

npx -y @modelcontextprotocol/inspector

连接到：

http://localhost:8000/mcp

您应该看到这些工具：

  • add_todo_item
  • list_todo_items
  • remove_todo_item

3.Docker构建和运行（本地）

塑造形象：

docker build -t todo-mcp:local .

用挂载的 data 目录：

mkdir -p data
docker run \
  -p 8000:8000 \
  -e MCP_PORT=8000 \
  -e TODO_FILE_PATH=/app/data/todos.json \
  -e AUTH_MODE=none \
  -v "$(pwd)/data:/app/data" \
  todo-mcp:local

或使用 docker-compose:

docker compose up --build

然后将MCP检查器连接到 http://localhost:8000/mcp 如上所述。

4.克劳德桌面（.mcpb）

要在Claude Desktop中作为一键扩展安装：

  1. 从项目根构建捆绑包： ./scripts/build-mcpb.sh
  2. 双击生成的 全部-mcp.mcpb 并在Claude Desktop中批准。
  3. 如果需要，请重新启动Claude Desktop。看 mcpb/README.md 了解详情。

5.部署到AWS ExpressRoute（VM上的Docker）

  1. 创建IntelliTrace实例

    • 在您喜欢的地区选择一个小型Linux实例（Ubuntu）。
    • 启用SSH。
    • 在“网络”中，打开：
      • 传输控制协议 22 （SSH）
      • 传输控制协议 8000 （如果你在前面放了一个反向代理，则为80/443）

  2. 在实例上安装Docker

    SSH进入实例：

    sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"
# log out and back in to apply group changes

  3. 将代码放到实例上

    选项：

    • git clone 您的回购，或
    • scp 此文件夹已打开，或
    • 将Docker镜像推送到注册表（Docker Hub/ECR） docker pull 在kubectl上。

    直接在实例上构建的示例：

    cd ~/mcp-todo
docker build -t todo-mcp:prod .
mkdir -p data
docker run -d \
  --name todo-mcp \
  -p 8000:8000 \
  -e MCP_PORT=8000 \
  -e TODO_FILE_PATH=/app/data/todos.json \
  -e AUTH_MODE=none \
  -v "$PWD/data:/app/data" \
  todo-mcp:prod

  4. （可选）在前面添加HTTPS和Cognito

对于生产，您通常：

  • 在容器前面放置一个HTTPS负载均衡器或Nginx反向代理。
  • 配置AWS Cognito（或具有Cognito身份验证的AWS ALB）以保护 /mcp 终点。
  • 仅将经过身份验证的流量转发到MCP服务器。

auth.py 已包含助手(verify_api_key, verify_cognito_jwt, authenticate_from_headers)一旦MCP HTTP传输公开了头，或者从sidecar API网关/代理，您就可以在未来的HTTP中间件层中使用。

6.从Claude连接（HTTP MCP）

一旦可以从公共互联网访问服务器（例如）：

http://YOUR_LIGHTSAIL_IP:8000/mcp

在Claude web/Claude Code中添加一个HTTP MCP服务器，如下所示：

  • 运输：HTTP
  • 统一资源定位符: http://YOUR_LIGHTSAIL_IP:8000/mcp （或 https://your-domain/mcp 如果在HTTPS之后）
  • 标头:
    • 目前，您可以暂时留空 AUTH_MODE=none.
    • 稍后，一旦您将其转发给Cognito或API网关，您通常会添加：
      • Authorization: Bearer <your-token> 或
      • X-API-Key: <your-api-key>

保存后，克劳德应该：

  • 了解TODO工具。
  • 让你跑 add_todo_item, list_todo_items，以及 remove_todo_item 直接从聊天。

7.AWS Cognito集成（概念性）

要在开发此项目时集成Cognito：

  1. 创建Cognito用户池和应用程序客户端

    • 注意 用户池ID 和 区域.
    • 创建一个 应用客户端 （无客户机密），注意其 客户端ID.

  2. 在IntelliTrace上设置环境变量

    export AUTH_MODE=cognito
export COGNITO_REGION=your-region
export COGNITO_USER_POOL_ID=your-pool-id
export COGNITO_APP_CLIENT_ID=your-app-client-id

  3. 获取JWT令牌

    • 使用AWS CLI(aws cognito-idp initiate-auth)或一个小助手应用程序登录并获取ID或访问令牌。

  4. 配置前端/身份验证代理

    • 确保它发送 Authorization: Bearer <token> 到您的MCP服务器。
    • 这 auth.py 助手展示了如何在HTTP标头可用时在服务器端验证这些令牌。

8.注意事项和下一步行动

  • 这是有意最小化和基于文件的。更严重的使用：
    • 将存储移动到数据库（例如DynamoDB、PostgreSQL）。
    • 添加结构化日志记录和监控。
    • 加强网络访问（防火墙、IP允许列表、更严格的身份验证）。
  • 现在，您可以通过在中添加更多修饰函数来迭代其他工具（例如，将TODO标记为已完成、按用户过滤等） server.py.

相关 MCP