Skip to main content
Glama
sqlite-notes

sqlite-notes

by walkerhughes

基于 Stytch 认证的 SQLite MCP

一个刻意保持精简的远程 MCP 服务,用于学习 SaaS 集成的形态:

  • FastMCP 通过 Streamable HTTP 提供六个工具。

  • Stytch Connected Apps 处理 OAuth 2.1 发现、动态客户端注册(Dynamic Client Registration)、PKCE、浏览器登录、同意和令牌签发。

  • 该服务根据 Stytch 轮换的 JWKS 验证每个访问令牌的签名、签发者、受众、过期时间和 openid 范围。

  • SQLite 行以令牌的 sub 为键,因此每个 Stytch 用户只能看到自己的笔记。

  • 即使 Stytch 客户端被意外配置了更长的访问令牌生命周期,服务器也将访问限制在 30 分钟内。

  • Claude Code 插件运行固定版本的 mcp-remote 桥接器,它执行 OAuth 并将 Claude Code 连接到远程 MCP 端点。

架构

Claude Code plugin -> http(s)://MCP/mcp -> validate Stytch JWT -> per-user SQLite CRUD
         |                                      ^
         +-> Stytch discovery -> browser login/consent app -> Stytch token endpoint

浏览器应用是必需的。Stytch 托管发现、注册和令牌端点,而你的应用托管用于登录和同意的 IdentityProvider 组件。

Related MCP server: Notebook MCP Server

1. 配置 Stytch

创建一个 Consumer Authentication 项目,然后配置:

  1. 在 Frontend SDK 中,启用 SDK 并授权 http://localhost:3000。

  2. 在 Redirect URLs 中,为登录和注册都添加 http://localhost:3000/authenticate。

  3. 启用 Email Magic Links,选择 Login or Create。

  4. 在 Connected Apps 中,将 Authorization URL 设置为 http://localhost:3000/oauth/authorize。

  5. 启用 Dynamic Client Registration。MCP 客户端使用 DCR,因为其回调端口可能变化。

  6. 在 Stytch 允许的范围内,将 Connected Apps 访问令牌过期时间设置为 30 分钟。

服务和插件只请求 openid,因为 MCP 服务器只需要稳定的 sub 标识符。它不需要 profile 或 email 数据。

服务器在每个访问令牌的 iat 之后 30 分钟拒绝该令牌。插件使用固定版本的 mcp-remote@0.2.1 桥接器,它请求 MCP 受保护资源通告的范围,而不添加 offline_access。因此 Stytch 不会签发刷新令牌,过期后用户将回到交互式授权。

这个桥接器是刻意为之的。原生 Claude Code OAuth 会在授权服务器通告 offline_access 时自动添加它,从而允许静默刷新令牌,使强制登录要求失效。

将 .env.example 复制为 .env 并设置:

  • STYTCH_PROJECT_ID:project-test-... 项目 ID,用作 JWT 受众。

  • STYTCH_DOMAIN:Stytch 显示的完整项目域名,例如 https://...customers.stytch.dev,用作签发者和 JWKS 主机。不要在此处使用 API 密钥或公共令牌。

  • STYTCH_PUBLIC_TOKEN:登录和同意 UI 使用的浏览器安全 public-token-test-... 值。

  • MCP_BASE_URL:MCP 服务器的外部可见源,不含 /mcp。

本项目不包含任何 Stytch 密钥。JWT 验证只需要公共签名密钥。

保存仪表板配置后,验证 Stytch 发现和签名密钥:

set -a; source .env; set +a
uv run python scripts/check_stytch.py

在打印出 PASS: Stytch authorization metadata and JWKS are ready for MCP OAuth. 之前,不要继续浏览器登录测试。

2. 本地运行

uv sync
set -a; source .env; set +a
uv run mcp-auth

在另一个终端中:

cd web
npm install
npm run dev

要进行真正的 OAuth 测试,MCP 端点和授权页面通常都应通过稳定的 HTTPS URL 访问。开发隧道可以发布 8000 和 3000 端口。将 MCP_BASE_URL、Stytch Frontend SDK 授权环境和重定向 URL、Connected Apps Authorization URL 以及 SQLITE_NOTES_MCP_URL 更新为这些 HTTPS URL。纯 localhost 设置在构建时很有用,但生产环境必须使用 HTTPS。

3. 安装并认证 Claude Code 插件

从仓库根目录注册本地市场并为该项目安装插件:

claude plugin marketplace add "$PWD" --scope project
claude plugin install sqlite-notes@mcp-auth-local --scope project

本地服务器 URL 默认为 http://127.0.0.1:8000/mcp。对于托管或隧道服务器,请在启动 Claude Code 之前设置 URL:

export SQLITE_NOTES_MCP_URL=https://your-mcp-tunnel.example/mcp

然后运行 /reload-plugins,打开 /mcp,选择 sqlite-notes。固定版本的 mcp-remote 桥接器通过 MCP 服务器发现 Stytch 授权服务器,自行注册,打开浏览器,使用 PKCE,并返回访问令牌。

尝试以下提示:

  • "创建一篇标题为 Grocery list、正文为 coffee and oranges 的笔记。"

  • "列出我的笔记。"

  • "更新笔记 1,添加 milk。"

  • "删除笔记 1。"

30 分钟后,MCP 服务器拒绝当前访问令牌。由于桥接器不请求 offline_access,它无法静默刷新,必须重复交互式授权。

测试

uv run pytest
cd web && npm run build

自动化测试涵盖 CRUD、跨用户隔离以及 30 分钟访问令牌边界。没有配置好的 Stytch 项目和电子邮件收件箱就无法自动化完整登录,因此浏览器流程是明确的手动端到端检查。

生产环境注意事项

SQLite 和单进程是本次练习的刻意选择。对于付费的多实例服务,请使用托管数据库、迁移、备份、HTTPS、结构化审计日志、速率限制和明确的授权范围。保持相同的边界:Stytch 对用户进行身份验证,而你的数据库和服务决定该用户可以访问哪些行和执行哪些操作。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local notes app that enables AI tools to manage notes via MCP (list, get, create, update, delete) using the same SQLite database as the GUI.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables users to create, retrieve, update, delete, and full-text search a local knowledge base of notes persisted in SQLite with FTS5, exposed over stdio or authenticated Streamable HTTP. It also surfaces recent/single-note resources and prompts for summarizing notes and drafting replies.
      5
      MIT