Guardia MCP

Guardia MCP服务器

一个具有70多种工具、OAuth 2.1身份验证和基于框架的工具过滤的生产模型上下文协议（MCP）服务器。使用Python和FastAPI构建。

它的作用

该服务器通过以下方式向AI助手（Claude等）公开工具 MCP协议。工具跨越多个领域——业务运营、交易、创意写作、基础设施等——组织成 帧 这让每个客户端只看到与其上下文相关的工具。

主要特点

• 70+工具 跨12个域模块，基于装饰器的自动注册
• 基于帧的过滤 --客户端请求帧(serberus, paradise, luna等），只查看相关工具
• OAuth 2.1 --具有PKCE、JWT（RS256）、刷新令牌的完全授权服务器
• 流式HTTP+SSE --与Claude.ai、Claude Desktop和自定义客户端兼容
• REST回退 — /mcp/tools 和 /mcp/call 非MCP客户端的端点
• Stdio大桥 — bridge.js 将Claude Desktop（stdio传输）连接到远程服务器

建筑

main.py                 FastAPI app, SSE endpoints, protocol wiring
config.py               Pydantic settings (env-driven)
bridge.js               Claude Desktop stdio-to-HTTP bridge

mcp/
  protocol.py           JSON-RPC message handling
  transport.py          HTTP/SSE transport layer
  sessions.py           Session management

auth/
  oauth_server.py       OAuth 2.1 authorization server
  jwt_handler.py        RS256 JWT signing/verification
  middleware.py          Request authentication
  models.py             Auth data models

tools/
  registry.py           @tool decorator, auto-registration, frame filtering
  cortex.py             Brain/awareness tools
  business.py           Client and revenue tools
  paradise.py           Trading system tools
  athernyx.py           Creative writing tools
  dev.py                Development utilities
  web.py                Web search and browsing
  atomic.py             System tools (shell, files, queries)
  ...                   (12 modules total)

db/
  cortex.py             Cortex database helpers
  spire.py              App database helpers
  oauth.py              OAuth token storage

添加工具

工具在装饰器中注册。把这个放在任何地方 tools/*.py 文件：

from tools.registry import tool, json_result, error_result

@tool(
    name="my_tool",
    description="What this tool does",
    properties={
        "input": {"type": "string", "description": "The input"}
    },
    required=["input"],
    frames=["core"]  # Which frames include this tool
)
async def my_tool(args: dict) -> dict:
    value = args.get("input", "")
    return json_result({"result": value})

注册表会在导入时自动发现所有已装饰的函数。

帧过滤

框架控制客户端看到哪些工具。通过 ?frame=X 在SSE连接URL上：

框架仅影响 tools/list --无论框架如何，所有工具都是可调用的。

设置

# Clone and install
git clone https://github.com/alexlaguardia/guardia-mcp.git
cd guardia-mcp
pip install -r requirements.txt

# Configure
cp .env.example .env
# Edit .env with your settings

# Generate RSA keys for JWT
mkdir -p keys
openssl genrsa -out keys/private.pem 2048
openssl rsa -in keys/private.pem -pubout -out keys/public.pem

# Run
python main.py
# Server starts on port 8100

连接客户

第ai条（远程）：

SSE URL: https://your-domain.com/sse?frame=serberus

克劳德桌面（stdio桥）：

{
  "mcpServers": {
    "guardia": {
      "command": "node",
      "args": ["bridge.js"],
      "env": {
        "MCP_BASE_URL": "https://your-domain.com",
        "MCP_DEV_KEY": "your-dev-key"
      }
    }
  }
}

堆栈

• 运行时间： Python 3.11+
• 框架： FastAPI+Uvicorn
• 认证： RS256 JWT、OAuth 2.1和PKCE
• 运输： 流式HTTP、SSE、stdio（通过网桥）
• 数据库： SQLite（通过原始查询）
• 流程经理： PM2

许可证

麻省理工学院