Metadata-Version: 2.4
Name: pymcp-auth-server
Version: 0.2.0
Summary: FastMCP server with token-based authentication and permission-controlled tool loading
Project-URL: Homepage, https://gitee.com/thirsd/pymcp_auth_server
Project-URL: Repository, https://gitee.com/thirsd/pymcp_auth_server
Project-URL: Issues, https://gitee.com/thirsd/pymcp_auth_server/issues
Author-email: thirsd <thirsd@sina.com>
License-Expression: MIT
Keywords: authentication,authorization,fastmcp,mcp,permission,token
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.4.0
Description-Content-Type: text/markdown

# pymcp-auth-server

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version: 0.2.0](https://img.shields.io/badge/version-0.2.0-green.svg)](https://gitee.com/thirsd/pymcp_auth_server)

基于 [FastMCP](https://github.com/jlowin/fastmcp) 的 MCP 认证服务器，提供 Token 认证与工具权限控制。认证/权限逻辑与工具业务代码完全解耦。

**Author:** [thirsd](mailto:thirsd@sina.com) | **License:** MIT | **Repo:** [Gitee](https://gitee.com/thirsd/pymcp_auth_server)

## 特性

- **Token 认证** — 通过 Bearer Token 鉴别用户身份
- **权限控制** — 不同用户只能看到和使用被授权的工具
- **运行时过滤** — 工具列表根据用户权限动态生成
- **业务解耦** — 工具函数不感知认证，只声明所需权限
- **多存储后端** — 支持 JSON 文件和 SQLite，可扩展
- **双传输模式** — SSE（HTTP）和 stdio

## 快速开始

### 安装

```bash
git clone https://gitee.com/thirsd/pymcp_auth_server.git
cd pymcp_auth_server
uv sync
```

### 30 秒示例

**1. 编写认证配置** `data/auth_config.json`：

```json
{
  "users": [
    {"username": "admin", "tokens": ["my-admin-token"], "permissions": ["*"]},
    {"username": "guest", "tokens": ["guest-token"], "permissions": ["calculator.add"]}
  ]
}
```

**2. 编写服务器** `my_server.py`：

```python
from mcp_auth_server import AuthMCPServer, JsonAuthStore

store = JsonAuthStore("data/auth_config.json")
server = AuthMCPServer("my-server", store=store)

@server.tool(permission="calculator.add")
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@server.tool(permission="calculator.multiply")
def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

@server.tool()  # 所有认证用户可用
def echo(message: str) -> str:
    """Echo a message."""
    return message

server.run(transport="sse", port=8000)
```

**3. 启动服务器**：

```bash
uv run python my_server.py
```

**4. 使用 MCP 客户端连接**（见下方 Claude Code 配置）。

## 权限模型

权限采用点分层级命名空间，支持三种匹配方式：

| 用户权限 | 说明 | 示例匹配 |
|----------|------|----------|
| `*` | 全部权限 | 匹配所有工具 |
| `calculator.*` | 前缀通配 | 匹配 `calculator.add`, `calculator.multiply` |
| `calculator.add` | 精确匹配 | 仅匹配 `calculator.add` |

工具不声明 `permission` 时，所有认证用户均可访问。

## Claude Code 客户端配置

### SSE 传输（推荐）

```json
{
  "mcpServers": {
    "auth-server": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer my-admin-token"
      }
    }
  }
}
```

### stdio 传输

```json
{
  "mcpServers": {
    "auth-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pymcp_auth_server", "python", "main.py"],
      "env": {
        "MCP_AUTH_TOKEN": "my-admin-token",
        "PYTHONPATH": "/path/to/pymcp_auth_server/src"
      }
    }
  }
}
```

## 项目结构

```
src/mcp_auth_server/
├── __init__.py               # 公共 API
├── __main__.py               # CLI 入口
├── server.py                 # AuthMCPServer 主类
├── examples.py               # 示例工具
├── auth/                     # 认证与权限模块
│   ├── models.py             #   UserInfo 数据模型
│   ├── manager.py            #   AuthManager 认证管理器
│   └── middleware.py         #   FastMCP 权限中间件
└── store/                    # 存储后端模块
    ├── base.py               #   AuthStore 抽象基类
    ├── json_store.py         #   JSON 文件存储
    └── sqlite_store.py       #   SQLite 数据库存储
```

## 作为库使用

```python
from mcp_auth_server import AuthMCPServer, JsonAuthStore, SQLiteAuthStore

# JSON 存储
store = JsonAuthStore("auth.json")

# 或 SQLite 存储
store = SQLiteAuthStore("auth.db")

# 管理用户
store.add_user("alice", "alice-token", ["file.read", "file.write"])
store.add_user("bob", "bob-token", ["file.read"])

# 创建服务器
server = AuthMCPServer("my-app", store=store)

@server.tool(permission="file.read")
def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

@server.tool(permission="file.write")
def write_file(path: str, content: str) -> str:
    with open(path, "w") as f:
        f.write(content)
    return "ok"

server.run(transport="sse", port=8000)
```

## CLI 使用

```bash
# 启动服务器
python -m mcp_auth_server serve --config data/auth_example.json --transport sse --port 8000

# 管理用户
python -m mcp_auth_server add-user --config auth.json --username admin --token xxx --permissions "*"
python -m mcp_auth_server list-users --config auth.json
python -m mcp_auth_server remove-user --config auth.json --username admin

# 使用 SQLite 后端
python -m mcp_auth_server serve --config auth.db --store sqlite --transport sse
```

## 扩展存储后端

在 `src/mcp_auth_server/store/` 下新建文件，继承 `AuthStore`：

```python
# store/redis_store.py
from .base import AuthStore

class RedisAuthStore(AuthStore):
    def __init__(self, url: str):
        ...

    def get_user_by_token(self, token: str):
        ...
    def add_user(self, username, token, permissions):
        ...
    def remove_user(self, username):
        ...
    def list_users(self):
        ...
```

在 `store/__init__.py` 中导出即可。

## 运行测试

```bash
uv run python tests/test_integration.py
```

## 文档

- [架构设计文档](docs/architecture.md) — 分层设计、请求流程、模块详解、扩展指南
- [API 参考](docs/api-reference.md) — 类、方法、CLI 完整接口说明

## 依赖

- Python >= 3.10
- [fastmcp](https://pypi.org/project/fastmcp/) >= 3.4.0（自带 Starlette / uvicorn）

## 许可证

[MIT License](LICENSE)

Copyright (c) 2025 thirsd (thirsd@sina.com)
