mcp-vos-auth

# mcp-vos-auth 用于 FastMCP 的工具调用鉴权 middleware。它在工具执行前通过 Vinehoo 接口验证 `token`， 再根据工具名查询允许调用该工具的角色；只有用户角色与工具角色存在交集时才执行工具。 ## 安装 ### 通过 PyPI 安装 ```bash pip install mcp-vos-auth ``` ### 不通过 pip 使用 无论采用下面哪种方式，目标项目都必须提供本包的运行依赖： ```bash pip install fastmcp httpx ``` #### 方式一：设置 `PYTHONPATH`（本地多项目开发推荐） 将本项目的 `src` 目录加入 Python 模块搜索路径： ```bash export PYTHONPATH="/path/to/mcp-vos-auth/src:$PYTHONPATH" python your_server.py ``` 例如本仓库位于 `/Users/vber/Documents/codes/mcp-vos-auth` 时： ```bash export PYTHONPATH="/Users/vber/Documents/codes/mcp-vos-auth/src:$PYTHONPATH" python your_server.py ``` 目标项目不需要修改导入语句： ```python from mcp_vos_auth import register_token_auth ``` `PYTHONPATH` 只对当前终端会话有效。需要长期使用时，可将 `export` 命令加入 shell 配置， 或写入项目的启动脚本。 #### 方式二：在程序入口添加源码路径（仅建议临时调试） ```python import sys sys.path.insert(0, "/path/to/mcp-vos-auth/src") from mcp_vos_auth import register_token_auth ``` 这种方式会把本机绝对路径写入业务代码，不适合多人协作或生产部署。 #### 方式三：将包源码复制到目标项目 把本仓库的 `src/mcp_vos_auth` 目录完整复制到目标项目根目录： ```text your-project/ ├── your_server.py └── mcp_vos_auth/ ├── __init__.py └── middleware.py ``` 然后正常导入： ```python from mcp_vos_auth import register_token_auth ``` 该方式部署简单，但复制后的源码不会自动同步本仓库后续的修复和升级，需要自行维护版本。 以上三种方式都不需要安装 `mcp-vos-auth` 本身。对于本地联调，优先使用 `PYTHONPATH`； 对于需要固定源码且不使用包管理的部署，可复制 `mcp_vos_auth` 目录。 ## 使用 调用默认 token 校验接口前，需要配置 MCP secret： ```bash export VINEHOO_MCP_SECRET="your-secret" ``` middleware 会将该值作为 `vinehoo-mcp-secret` 请求 header 发送。 ```python from fastmcp import Context, FastMCP from mcp_vos_auth import get_token_data, register_token_auth mcp = FastMCP("protected-server") # 自动创建 middleware 并注册到当前 FastMCP 实例。 register_token_auth(mcp, platform="app") @mcp.tool def get_order(order_id: int, token: str) -> dict: return {"order_id": order_id} if __name__ == "__main__": mcp.run() ``` 工具函数可通过 FastMCP 注入的 `Context` 获取校验接口返回的完整 `data`，包括 `telephone`、`uid`、`userid`、`realname` 和 `roles`： ```python @mcp.tool async def current_user(token: str, ctx: Context) -…