mcp-vos-auth 0.1.0__tar.gz

mcp_vos_auth-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+build/
+dist/
+*.egg-info/

mcp_vos_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinehoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_vos_auth-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mcp-vos-auth
+Version: 0.1.0
+Summary: Token validation middleware for FastMCP tools
+Project-URL: Repository, https://github.com/vinehoo/mcp-vos-auth
+Author: vber
+License: MIT
+License-File: LICENSE
+Keywords: authentication,fastmcp,mcp,middleware
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4,>=2.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pip>=26.1.2
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-vos-auth
+
+用于 FastMCP 的工具调用 token 校验 middleware。它在工具执行前读取工具名、参数和
+`token` 参数，通过 Vinehoo `check_token` 接口验证 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` 目录。
+
+## 使用
+
+```python
+from fastmcp import FastMCP
+from mcp_vos_auth import 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()
+```
+
+不传 `platform` 时校验中台用户：
+
+```python
+register_token_auth(mcp)
+```
+
+默认保护所有工具。可排除公开工具，或只保护指定工具：
+
+```python
+register_token_auth(mcp, excluded_tools={"health", "version"})
+# 或
+register_token_auth(mcp, protected_tools={"get_order", "delete_order"})
+```
+
+其他配置：
+
+```python
+register_token_auth(
+    mcp,
+    token_parameter="access_token",
+    timeout=3.0,
+    unauthorized_message="无权限",
+)
+```
+
+如果工具使用 Pydantic 模型等嵌套参数，可以用点路径指定 token 的位置：
+
+```python
+@mcp.tool
+async def submit_feedback(params: SubmitFeedbackInput) -> str:
+    ...
+
+register_token_auth(mcp, token_parameter="params.token")
+```
+
+`on_validation` 回调可获取工具名、完整工具参数和标准化校验结果。请勿在日志中记录完整
+token：
+
+```python
+async def audit(tool_name, arguments, result):
+    print(tool_name, result.valid, result.data)
+
+register_token_auth(mcp, on_validation=audit)
+```
+
+安全策略为 fail-closed：缺少 token、HTTP 401、`error_code != 0`、响应格式异常、网络错误
+或超时都会阻止工具执行。token 参数仍会传给工具函数；如工具不需要使用它，可以保留该
+参数但不要记录或返回它。
+
+## 构建和发布
+
+```bash
+python -m pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+发布前请在 `pyproject.toml` 中确认包名、作者、Repository URL 和版本号。
+
+## 测试
+
+```bash
+python -m pip install -e '.[test]'
+pytest
+```

mcp_vos_auth-0.1.0/README.md

@@ -0,0 +1,166 @@
+# mcp-vos-auth
+
+用于 FastMCP 的工具调用 token 校验 middleware。它在工具执行前读取工具名、参数和
+`token` 参数，通过 Vinehoo `check_token` 接口验证 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` 目录。
+
+## 使用
+
+```python
+from fastmcp import FastMCP
+from mcp_vos_auth import 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()
+```
+
+不传 `platform` 时校验中台用户：
+
+```python
+register_token_auth(mcp)
+```
+
+默认保护所有工具。可排除公开工具，或只保护指定工具：
+
+```python
+register_token_auth(mcp, excluded_tools={"health", "version"})
+# 或
+register_token_auth(mcp, protected_tools={"get_order", "delete_order"})
+```
+
+其他配置：
+
+```python
+register_token_auth(
+    mcp,
+    token_parameter="access_token",
+    timeout=3.0,
+    unauthorized_message="无权限",
+)
+```
+
+如果工具使用 Pydantic 模型等嵌套参数，可以用点路径指定 token 的位置：
+
+```python
+@mcp.tool
+async def submit_feedback(params: SubmitFeedbackInput) -> str:
+    ...
+
+register_token_auth(mcp, token_parameter="params.token")
+```
+
+`on_validation` 回调可获取工具名、完整工具参数和标准化校验结果。请勿在日志中记录完整
+token：
+
+```python
+async def audit(tool_name, arguments, result):
+    print(tool_name, result.valid, result.data)
+
+register_token_auth(mcp, on_validation=audit)
+```
+
+安全策略为 fail-closed：缺少 token、HTTP 401、`error_code != 0`、响应格式异常、网络错误
+或超时都会阻止工具执行。token 参数仍会传给工具函数；如工具不需要使用它，可以保留该
+参数但不要记录或返回它。
+
+## 构建和发布
+
+```bash
+python -m pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+发布前请在 `pyproject.toml` 中确认包名、作者、Repository URL 和版本号。
+
+## 测试
+
+```bash
+python -m pip install -e '.[test]'
+pytest
+```

mcp_vos_auth-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-vos-auth"
+version = "0.1.0"
+description = "Token validation middleware for FastMCP tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "vber" }]
+keywords = ["fastmcp", "mcp", "middleware", "authentication"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "fastmcp>=2.11,<4",
+  "httpx>=0.27,<1",
+  "pip>=26.1.2",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Repository = "https://github.com/vinehoo/mcp-vos-auth"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_vos_auth"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+

mcp_vos_auth-0.1.0/src/mcp_vos_auth/__init__.py

@@ -0,0 +1,18 @@
+"""FastMCP token authentication middleware."""
+
+from .middleware import (
+    DEFAULT_CHECK_TOKEN_URL,
+    TokenAuthMiddleware,
+    TokenValidationResult,
+    register_token_auth,
+)
+
+__all__ = [
+    "DEFAULT_CHECK_TOKEN_URL",
+    "TokenAuthMiddleware",
+    "TokenValidationResult",
+    "register_token_auth",
+]
+
+__version__ = "0.1.0"
+

mcp_vos_auth-0.1.0/src/mcp_vos_auth/middleware.py

@@ -0,0 +1,169 @@
+"""Vinehoo token validation middleware for FastMCP."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Collection
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from fastmcp.exceptions import ToolError
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+DEFAULT_CHECK_TOKEN_URL = (
+    "https://callback.vinehoo.com/go-wechat/wechat/v3/other/check_token"
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class TokenValidationResult:
+    """Normalized result returned by the token validation endpoint."""
+
+    valid: bool
+    data: dict[str, Any] | None = None
+    error_code: int | None = None
+    error_message: str | None = None
+
+
+ValidationCallback = Callable[
+    [str, dict[str, Any], TokenValidationResult], Awaitable[None] | None
+]
+
+
+class TokenAuthMiddleware(Middleware):
+    """Validate a token argument before executing a FastMCP tool.
+
+    Validation is fail-closed: missing tokens, invalid responses, timeouts, and
+    validator service failures all deny the tool call.
+    """
+
+    def __init__(
+        self,
+        *,
+        check_url: str = DEFAULT_CHECK_TOKEN_URL,
+        platform: str | None = None,
+        token_parameter: str = "token",
+        timeout: float = 5.0,
+        unauthorized_message: str = "无权限",
+        protected_tools: Collection[str] | None = None,
+        excluded_tools: Collection[str] = (),
+        client: httpx.AsyncClient | None = None,
+        on_validation: ValidationCallback | None = None,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        if protected_tools is not None and excluded_tools:
+            raise ValueError("protected_tools and excluded_tools cannot be used together")
+
+        self.check_url = check_url
+        self.platform = platform
+        self.token_parameter = token_parameter
+        self.timeout = timeout
+        self.unauthorized_message = unauthorized_message
+        self.protected_tools = frozenset(protected_tools) if protected_tools else None
+        self.excluded_tools = frozenset(excluded_tools)
+        self._client = client
+        self.on_validation = on_validation
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next: Any) -> Any:
+        tool_name = context.message.name
+        arguments = dict(context.message.arguments or {})
+
+        if not self._is_protected(tool_name):
+            return await call_next(context)
+
+        token = self._get_argument(arguments, self.token_parameter)
+        if not isinstance(token, str) or not token.strip():
+            await self._notify(tool_name, arguments, TokenValidationResult(
+                valid=False, error_message="missing token"
+            ))
+            raise ToolError(self.unauthorized_message)
+
+        result = await self.validate_token(token.strip())
+        await self._notify(tool_name, arguments, result)
+        if not result.valid:
+            logger.warning(
+                "Denied FastMCP tool call: tool=%s error_code=%s error=%s",
+                tool_name,
+                result.error_code,
+                result.error_message,
+            )
+            raise ToolError(self.unauthorized_message)
+
+        return await call_next(context)
+
+    def _is_protected(self, tool_name: str) -> bool:
+        if self.protected_tools is not None:
+            return tool_name in self.protected_tools
+        return tool_name not in self.excluded_tools
+
+    @staticmethod
+    def _get_argument(arguments: dict[str, Any], path: str) -> Any:
+        """Read an argument using a dotted path such as ``params.token``."""
+
+        value: Any = arguments
+        for part in path.split("."):
+            if not part or not isinstance(value, dict):
+                return None
+            value = value.get(part)
+        return value
+
+    async def validate_token(self, token: str) -> TokenValidationResult:
+        params = {"platform": self.platform} if self.platform is not None else None
+        headers = {"VINEHOO-Authorization": f"Bearer {token}"}
+
+        try:
+            if self._client is not None:
+                response = await self._client.get(
+                    self.check_url, headers=headers, params=params, timeout=self.timeout
+                )
+            else:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        self.check_url, headers=headers, params=params, timeout=self.timeout
+                    )
+        except httpx.HTTPError as exc:
+            logger.exception("Token validation request failed")
+            return TokenValidationResult(valid=False, error_message=str(exc))
+
+        try:
+            payload = response.json()
+        except ValueError:
+            return TokenValidationResult(
+                valid=False,
+                error_message=f"validator returned non-JSON response ({response.status_code})",
+            )
+
+        if not isinstance(payload, dict):
+            return TokenValidationResult(valid=False, error_message="invalid validator response")
+
+        error_code = payload.get("error_code")
+        error_message = payload.get("error_msg")
+        data = payload.get("data")
+        valid = response.status_code == 200 and error_code == 0 and isinstance(data, dict)
+        return TokenValidationResult(
+            valid=valid,
+            data=data if isinstance(data, dict) else None,
+            error_code=error_code if isinstance(error_code, int) else None,
+            error_message=error_message if isinstance(error_message, str) else None,
+        )
+
+    async def _notify(
+        self, tool_name: str, arguments: dict[str, Any], result: TokenValidationResult
+    ) -> None:
+        if self.on_validation is None:
+            return
+        callback_result = self.on_validation(tool_name, arguments, result)
+        if callback_result is not None:
+            await callback_result
+
+
+def register_token_auth(server: Any, **kwargs: Any) -> TokenAuthMiddleware:
+    """Create and register token authentication middleware on a FastMCP server."""
+
+    middleware = TokenAuthMiddleware(**kwargs)
+    server.add_middleware(middleware)
+    return middleware