mcp-personal · 个人 MCP 服务器

用 Python（FastMCP）构建的个人 MCP 服务器，可接入 Cursor / VS Code / DeepSeek Harness 等任意 MCP 客户端。

完整规划见 PLAN.md · 展示素材见 docs/展示指南.md · 当前进度：四大场景 + HTTP + 鉴权 + pdf_extract ✅ · 21 个测试通过 · 环境变量见 .env.example

快速开始

# 1. 创建虚拟环境并安装（需 Python 3.11+ 或 uv）
uv venv
uv pip install -e ".[dev]"

# 2. 跑测试
uv run pytest tests -q

# 3. 启动服务器（stdio，供客户端接入）
uv run python -m mcp_personal

# 4. 冒烟测试：真实 stdio 子进程链路
uv run python scripts/smoke_stdio.py

# 5. 查看服务器注册的能力清单（Tools/Prompts/Resources）
uv run python scripts/verify_capabilities.py

# 6. 调试：官方 MCP Inspector
uv run mcp dev src/mcp_personal/server.py

接入客户端

配置已预置（portable 写法：uv run --project . 自动定位环境，仓库可任意移动）：

客户端	配置文件
Cursor	.cursor/mcp.json（设置 → MCP → 添加本地服务器）
VS Code	.vscode/mcp.json（需安装 "MCP" 扩展 / Copilot Chat）
其他	标准 stdio 配置：command + args 同上

接入后先让 AI 调用 ping 工具验证链路。

HTTP 远程接入（可选）

# 终端 1：启动 HTTP 服务（默认 127.0.0.1:8000，--host 0.0.0.0 可局域网访问）
uv run python scripts/run_http.py --port 8000

# 终端 2：用官方客户端验证链路
uv run python scripts/client_http_check.py --url http://127.0.0.1:8000/mcp

其他远程客户端把 MCP 服务器地址配成 http://<host>:<port>/mcp 即可。

HTTP 鉴权（可选）

设置环境变量后启动，所有请求需携带 Authorization: Bearer <token>：

# 终端 1：带鉴权启动
MCP_API_TOKEN=my-secret uv run python scripts/run_http.py --port 8000

# 终端 2：带 token 验证
uv run python scripts/client_http_check.py --url http://127.0.0.1:8000/mcp --token my-secret

说明：基于 FastMCP 官方 StaticTokenVerifier（API key 风格），token 明文存储，仅适合个人/开发用途；生产应改用 OAuth/JWT。

目录结构

├── PLAN.md            # 项目规划书
├── pyproject.toml     # 依赖与打包
├── src/mcp_personal/  # 服务器代码
│   ├── server.py      # FastMCP 入口（注册全部原语）
│   ├── tools/         # Tool：paper(检索)/dataset(摸底)/scaffold(课设)/devtools(目录树)
│   ├── prompts.py     # Prompt：literature_review 文献综述框架
│   └── resources.py   # Resource：papers://list 本地论文库
├── papers/            # 本地论文库（放 PDF）
├── datasets/          # 竞赛数据集（dataset_info 工具使用）
├── tests/             # pytest 测试（13 个）
├── .github/workflows/ # CI：push/PR 自动跑测试
├── scripts/           # smoke_stdio.py / verify_capabilities.py
├── .cursor/ .vscode/  # 客户端接入配置
└── README.md