{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_qxu4cpcv9cam","handle":"mcp-vos-auth","url":"https://wellknown.network/agents/mcp-vos-auth","links":{"self":"https://wellknown.network/agents/mcp-vos-auth/record.json","html":"https://wellknown.network/agents/mcp-vos-auth","markdown":"https://wellknown.network/agents/mcp-vos-auth/record.md","api":"https://wellknown.network/api/v1/agents/mcp-vos-auth","status":"https://wellknown.network/api/v1/agents/mcp-vos-auth/status","claim":"https://wellknown.network/agents/mcp-vos-auth/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/mcp-vos-auth/claim.json","badge":"https://wellknown.network/agents/mcp-vos-auth/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/mcp-vos-auth/history","tools":"https://wellknown.network/api/v1/agents/mcp-vos-auth/tools"},"ard":{"identifier":"urn:air::server:mcp-vos-auth","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"mcp-vos-auth","summary":"Token validation middleware for FastMCP tools","description":"# mcp-vos-auth\n\n用于 FastMCP 的工具调用鉴权 middleware。它在工具执行前通过 Vinehoo 接口验证 `token`，\n再根据工具名查询允许调用该工具的角色；只有用户角色与工具角色存在交集时才执行工具。\n\n## 安装\n\n### 通过 PyPI 安装\n\n```bash\npip install mcp-vos-auth\n```\n\n### 不通过 pip 使用\n\n无论采用下面哪种方式，目标项目都必须提供本包的运行依赖：\n\n```bash\npip install fastmcp httpx\n```\n\n#### 方式一：设置 `PYTHONPATH`（本地多项目开发推荐）\n\n将本项目的 `src` 目录加入 Python 模块搜索路径：\n\n```bash\nexport PYTHONPATH=\"/path/to/mcp-vos-auth/src:$PYTHONPATH\"\npython your_server.py\n```\n\n例如本仓库位于 `/Users/vber/Documents/codes/mcp-vos-auth` 时：\n\n```bash\nexport PYTHONPATH=\"/Users/vber/Documents/codes/mcp-vos-auth/src:$PYTHONPATH\"\npython your_server.py\n```\n\n目标项目不需要修改导入语句：\n\n```python\nfrom mcp_vos_auth import register_token_auth\n```\n\n`PYTHONPATH` 只对当前终端会话有效。需要长期使用时，可将 `export` 命令加入 shell 配置，\n或写入项目的启动脚本。\n\n#### 方式二：在程序入口添加源码路径（仅建议临时调试）\n\n```python\nimport sys\n\nsys.path.insert(0, \"/path/to/mcp-vos-auth/src\")\n\nfrom mcp_vos_auth import register_token_auth\n```\n\n这种方式会把本机绝对路径写入业务代码，不适合多人协作或生产部署。\n\n#### 方式三：将包源码复制到目标项目\n\n把本仓库的 `src/mcp_vos_auth` 目录完整复制到目标项目根目录：\n\n```text\nyour-project/\n├── your_server.py\n└── mcp_vos_auth/\n    ├── __init__.py\n    └── middleware.py\n```\n\n然后正常导入：\n\n```python\nfrom mcp_vos_auth import register_token_auth\n```\n\n该方式部署简单，但复制后的源码不会自动同步本仓库后续的修复和升级，需要自行维护版本。\n\n以上三种方式都不需要安装 `mcp-vos-auth` 本身。对于本地联调，优先使用 `PYTHONPATH`；\n对于需要固定源码且不使用包管理的部署，可复制 `mcp_vos_auth` 目录。\n\n## 使用\n\n调用默认 token 校验接口前，需要配置 MCP secret：\n\n```bash\nexport VINEHOO_MCP_SECRET=\"your-secret\"\n```\n\nmiddleware 会将该值作为 `vinehoo-mcp-secret` 请求 header 发送。\n\n```python\nfrom fastmcp import Context, FastMCP\nfrom mcp_vos_auth import get_token_data, register_token_auth\n\nmcp = FastMCP(\"protected-server\")\n\n# 自动创建 middleware 并注册到当前 FastMCP 实例。\nregister_token_auth(mcp, platform=\"app\")\n\n@mcp.tool\ndef get_order(order_id: int, token: str) -> dict:\n    return {\"order_id\": order_id}\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n工具函数可通过 FastMCP 注入的 `Context` 获取校验接口返回的完整 `data`，包括\n`telephone`、`uid`、`userid`、`realname` 和 `roles`：\n\n```python\n@mcp.tool\nasync def current_user(token: str, ctx: Context) -…","publisher":{"name":"vber","url":null},"homepage":null,"repository":"https://github.com/vinehoo/mcp-vos-auth","version":"0.1.4","license":"MIT","protocols":["mcp"],"tags":["authentication","fastmcp","mcp","middleware"],"pricing":null,"endpoints":[{"url":"pypi:mcp-vos-auth","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","repoUrl":"pypi","summary":"pypi","version":"pypi","description":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"security.identity","name":"Identity & Access","confidence":1,"provenance":"declared"},{"slug":"dev.terminal","name":"Terminal & Shell","confidence":0.745,"provenance":"derived"}],"categories":["dev","security"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"mcp-vos-auth","registry":"pypi","observedAt":"2026-10-28T15:25:45.049Z","publishedAt":"2026-07-07T01:35:27.675758Z","latestVersion":"0.1.4"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"mcp-vos-auth","url":"https://pypi.org/project/mcp-vos-auth/","firstSeenAt":"2026-09-10T05:21:51.744Z","fetchedAt":"2026-10-28T15:23:36.477Z","normalizedAt":"2026-10-28T15:23:36.477Z"}]},"firstSeenAt":"2026-09-10T05:21:51.744Z","updatedAt":"2026-10-28T15:25:45.049Z"}