AI导哈

认证服务示例

一个最小化的FastMCP服务器，展示了生产就绪的认证架构，支持令牌和OAuth两种认证方式。

  • by lqdflying
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lqdflying/MCP-Sample

使用说明

MCP身份验证示例

最低限度 FastMCP 演示生产就绪身份验证的服务器 MCP服务器的架构。它附带了一个示例工具(hello_world_tool) 因此，重点仍然放在身份验证层上。

支持的身份验证模式：

  • 令牌 --静态承载令牌(MCP_API_TOKEN)
  • OAuth --GitHub OAuth（OAuth 2.1代理+OAuth 2.0原始令牌验证器）
  • 两者 --在同一服务器上接受任一方法（默认）

GitHub OAuth包含一个可选 登录列表 这样你就可以限制访问 针对特定的GitHub用户，以及结构化的 审计日志 对于每一个认证决定。

项目布局

server.py                 — FastMCP server factory, middleware, /health, sample tool
src/debug.py              — Structured JSON logging, field redaction, trace IDs
src/auth/provider.py      — setup_auth() reads env vars and builds the auth provider
src/auth/oauth.py         — Login-filtered GitHubProvider + GitHubTokenVerifier
src/auth/oauth_url.py     — Loopback URL normalization (https→http for local OAuth)
src/auth/token.py         — Constant-time static token verifier
src/tools/sample_tools.py — hello_world reference tool
tests/                    — pytest suite for the sample tool
docs/                     — Architecture diagrams (excalidraw) and OAuth callback notes

快速开始

git clone <this-repo-url>
cd MCP-Sample
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

编辑 .env 并设置为最小值：

MCP_AUTH_MODE=token
MCP_API_TOKEN=your_secret_mcp_token_here

启动服务器：

python server.py

健康检查：

curl http://localhost:8000/health

启用GitHub OAuth

寄存器A GitHub OAuth应用程序 随着 回调URL ${BASE_URL}/auth/callback，然后设置：

MCP_AUTH_MODE=both
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
BASE_URL=https://your-public-host.example.com
GITHUB_OAUTH_SCOPES=read:user
ALLOWED_GITHUB_LOGINS=your-github-login

看 docs/github-oauth-callback-guide.md 和 docs/oauth-callback-workflows.md 为了 回调流。

结构化JSON日志记录

所有日志都以JSONL（每行一个JSON对象）的形式发送到stderr。每个工具 该调用获取一个UUID 4跟踪ID，用于跨异步上下文关联日志条目。

集 MCP_DEBUG=true 以启用结构化调试事件（工具调用开始/结束， 认证决定）。敏感字段（SQL、args、错误、回溯）包括 使用长度+SHA指纹自动编辑。设置 MCP_DEBUG_VERBOSE=true 禁用本地开发的编辑功能。

日志中间件从不包含原始工具参数或 str(e) 在 生产日志行——只记录异常类型以防止泄漏 来自下游服务的敏感数据。

环回URL规范化

当 BASE_URL 指向环回地址(127.0.0.1, localhost, ::1), 这 https:// 方案会自动重写为 http:// 根据 RFC 8252。 这处理了IDE公开的VS代码/游标端口转发场景 服务器为HTTPS，但本地侦听器仅支持HTTP。

添加自己的工具

src/tools/sample_tools.py 是模板--定义一个 async 功能和 再出口 src/tools/__init__.py。然后在里面注册 create_server() 在 server.py 随着 @mcp.tool(...).

发展

pip install -e ".[dev]"
pytest
ruff check .

码头工人

docker compose up --build

技术栈

  • Python 3.12+
  • FastMCP ≥3.3.1-MCP服务器框架，内置OAuth 2.1代理支持
  • httpx --异步HTTP客户端（GitHub令牌验证）
  • python dotenv --负载 .env 文件
  • pytest+pytest异步 --试验转轮
  • 颈毛 --linter和格式化器

相关 MCP