AI导哈

笔记MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，用于个人笔记管理，支持通过WorkOS AuthKit进行认证和授权。

  • by maadhaov-janumula
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 maadhaov-janumula/MCP_notes

使用说明

备注MCP服务器（FastMCP+WorkOS AuthKit）

用于个人笔记的生产就绪模型上下文协议（MCP）服务器。使用FastMCP通过WorkOS AuthKit处理身份验证和授权 AuthKitProvider，从JWT强制执行RBAC permissions 声称。

建筑

MCP Client (ChatGPT, etc)
        │
        ├─ OAuth 2.1 via AuthKitProvider (dynamic client registration, JWKS, token validation)
        │
FastMCP HTTP transport (/mcp JSON-RPC)
        │
        └─ Notes tools -> SQLite (async SQLAlchemy)
  • 身份/RBAC的真实来源： WorkOS身份验证工具包 （访问令牌中的角色+权限）。
  • 本地数据库仅存储用户（按 sub)以及他们的笔记。

角色和权限

角色 权限 允许的工具
notes_reader notes:read list_notes, get_note
notes_admin notes:read, notes:write 所有工具(list_notes, get_note, create_note, update_note, delete_note)

所有权：每个工具都按以下方式过滤 sub → local owner_user_id.访问其他用户的笔记会引起 ToolError("Access denied: You do not own this note").

先决条件

  • Python 3.11+
  • 启用AuthKit和MCP动态客户端注册的WorkOS项目

设置

  1. 安装依赖项：
    pip install -r requirements.txt
  2. 配置WorkOS/AuthKit：
    • 使用OAuth 2.1+动态客户端注册（MCP）启用AuthKit。
    • 注意您的AuthKit域（例如。， https://your-project-12345.authkit.app).
    • 定义权限： notes:read, notes:write.
    • 定义角色：
      • notes_reader → notes:read
      • notes_admin → notes:read, notes:write
    • 确保访问令牌包括 sub, permissions，可选 role, org_id，以及 email.
  3. 环境：
    • 复制 .env.example 到 .env 并填写数值。
    • 关键变量：
      • FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.AuthKitProvider
  • FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN
  • FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_BASE_URL
  • FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_REQUIRED_SCOPES
  • DATABASE_URL
  • WORKOS_API_KEY （通过WorkOS用户管理/RBAC API进行RBAC水合）
  • WORKOS_API_BASE （可选，默认为https://api.workos.com)

RBAC/WorkOS

权限来源于WorkOS组织成员资格及其角色段(notes_reader, notes_admin).服务器使用 WORKOS_API_KEY 调用WorkOS用户管理 list_organization_memberships(user_id=...)，通过内部映射角色 ROLE_PERMISSIONS，并强制执行 notes:read/notes:write 在工具中。AuthKit MCP令牌目前不携带权限，因此需要从WorkOS进行水合。 4.数据库初始化：

  • 启动时会自动创建表(init_db() 在负载期间运行）。

跑步

通过HTTP传输启动MCP服务器：

fastmcp run main.py --transport http --port 8000
  • 服务器在以下位置公开MCP JSON-RPC http://localhost:8000/mcp.
  • AuthKitProvider发布OAuth元数据；MCP客户端通过AuthKit执行OAuth。

工具

  • list_notes --要求 notes:read；返回来电者的留言。
  • get_note(note_id) --要求 notes:read；所有权强制执行。
  • create_note(title, body) --要求 notes:write；创建呼叫者拥有的笔记。
  • update_note(note_id, body) --要求 notes:write；所有权强制执行。
  • delete_note(note_id) --要求 notes:write；所有权强制执行。

MCP客户端示例（Python）

import asyncio
from fastmcp import Client


async def main():
    client = Client("http://localhost:8000/mcp", auth="oauth")
    await client.authenticate()  # triggers AuthKit OAuth flow

    print(await client.call_tool("list_notes"))
    note = await client.call_tool("create_note", {"title": "Hello", "body": "World"})
    fetched = await client.call_tool("get_note", {"note_id": note["id"]})
    print(fetched)

asyncio.run(main())

RBAC测试流程

  • 读卡器尝试写入: create_note → ToolError: Access denied: Missing required permission 'notes:write'.
  • 管理员：可以创建/更新/删除；仍然仅限于自己的笔记。
  • 跨用户访问：请求其他用户的注释→ ToolError: Access denied: You do not own this note.

故障排除

  • AuthKit域/基本URL配置错误→ 令牌验证或元数据错误；验证 .env.
  • 缺失 FASTMCP_SERVER_AUTH → auth未激活；确保设置了环境变量。
  • 空数据库文件→ 确保服务器启动一次（表自动创建）。
  • 令牌缺少权限→ 预期 Access denied ToolError 响应。

相关 MCP