跳到內容
Surfski

Development

本頁內容尚未翻譯。

Terminal window
uv sync
Terminal window
uv run pytest

The tests never contact Google. Gmail and the token endpoints are mocked, and the caller’s identity is injected.

For a local run, set BASE_URL=http://localhost:8000 and add http://localhost:8000/auth/callback and /gmail/callback to your OAuth client:

Terminal window
set -a; source ./local.env; set +a; uv run surfski

Library notes

Section titled “Library notes”
  • Built on fastmcp 4.x (fastmcp>=4.1,<5) using GoogleProvider. Google doesn’t support Dynamic Client Registration, so FastMCP runs an OAuth proxy that Claude registers against.
  • OAuth client storage is key_value.aio.stores.filetree.FileTreeStore wrapped in FernetEncryptionWrapper. It’s single-node, with no Redis.
  • The MCP client redirect allowlist defaults to https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback.
  • Google reports email_verified either as the string "true" (tokeninfo) or as a boolean (userinfo), and both forms are handled.
  • Mailbox linking talks to Google’s token, revoke and profile endpoints directly with httpx, and uses PKCE (S256) with signed, single-use, 10-minute state.

Synced from rayhu/surfski/README.md@e4c5de0. The repository is the source of truth.