补充说明MCP
一个TypeScript MCP服务器，将索引卡写入Supabase，部署在Google Cloud Run上。
MCP工具
| 工具 | 说明 |
|---|---|
health | 检查服务器状态和Supabase连接 |
write_cards | 验证并更新带有修订历史的索引卡 |
lookup_card_by_id | 按UUID列表查找特定索引卡（不包括软删除） |
lookup_categories | 获取活动卡中使用的所有唯一类别 |
lookup_projects | 获取活动卡中使用的所有唯一项目标识符 |
lookup_tags | 获取活动卡中使用的所有唯一lvl0/lvl1标签 |
search_cards | 按类别/标签/项目/事实进行关键字搜索（不包括软删除） |
建筑
先决条件
- Node.js 22+
- Docker（用于容器化部署）
- 谷歌云CLI(
gcloud)--用于云运行部署 - 应用了模式的Supabase项目
设置
# Install dependencies and git hooks
make install环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
SUPABASE_URL | ✅ | Supabase项目URL |
SUPABASE_SERVICE_ROLE_KEY | ✅ | Supabase服务角色键 |
SUPABASE_ANON_KEY | ✅ | Supabase匿名密钥（身份验证UI） |
SUPABASE_ACCESS_TOKEN | ❌ | Supabase CLI/MCP令牌（仅应用远程迁移时需要） |
PORT | ❌ | 服务器端口（默认值： 8080) |
PUBLIC_URL | ✅ | OAuth和MCP传输端点的公共URL |
SERVER_VERSION | ❌ | 客户端缓存破坏的MCP/OpenAPI版本提示（默认值： 1.0.0) |
认证
此服务器使用 Supabase认证 通过OAuth 2.0进行所有MCP操作。MCP客户端（如ChatGPT）将通过以下方式自动发现OAuth配置：
/.well-known/oauth-authorization-server/.well-known/oauth-protected-resource
标准 Authorization: Bearer MCP传输端点需要标头。
ChatGPT SDK端点
OpenAPI表面位于 /openapi.json 公开了这些与工具兼容的REST端点：
POST /api/write-cardsPOST /api/lookup-card-by-idGET /api/lookup-categoriesGET /api/lookup-projectsGET /api/lookup-tagsPOST /api/search-cards
lookup-card-by-id 需要一个数组有效负载：
{
"ids": ["", ""]
}添加/更改工具时，碰撞 SERVER_VERSION 在部署之前，ChatGPT会刷新缓存的工具元数据。
数据库模式
将迁移应用于 supabase/migrations 使用Supabase CLI或SQL编辑器。保持RLS启用，如果触及策略，请重新运行lint。
发展
# Start dev server with hot reload
make dev
# Run tests
make test
# Run tests with coverage
make test-coverage
# Lint and format
make lint
make format
# Run all CI checks locally
make ai-checks码头工人
# Build
docker build -t supascribe-notes-mcp .
# Run
docker run -p 8080:8080 --env-file .env supascribe-notes-mcp部署到云端运行
# Set your GCP project
gcloud config set project anchildress1-unstable
# Deploy
bash deploy.sh部署后，验证服务是否正在运行：
# Replace with your deployed Cloud Run service URL
# You can find this in the Cloud Run console or with:
# gcloud run services describe supascribe-notes --region YOUR_REGION --format='value(status.url)'
SERVICE_URL="https://your-service-url"
# 1. Health check (Public)
curl "$SERVICE_URL/status"
# 2. Streamable HTTP initialize (Requires Auth)
# Replace YOUR_TOKEN with a valid Supabase JWT
curl -i -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}' \
"$SERVICE_URL/mcp"初始化响应返回 Mcp-Session-Id 在响应标头中。在后续的MCP请求中使用该标头。
要全面测试MCP功能，请配置MCP客户端以连接到Streamable HTTP端点：
- 统一资源定位符:
$SERVICE_URL/mcp - 认证：使用客户端支持的标准OAuth 2.1流，指向Supabase项目的身份验证端点。
卡片形状
{
"objectID": "uuid (auto-generated)",
"title": "string (required)",
"blurb": "string (required)",
"fact": "string (required)",
"url": "string (optional, must be valid URL)",
"tags": { "lvl0": ["string"], "lvl1": ["string"] }, // both arrays are required (use [] when empty)
"projects": ["string"],
"category": "string (required)",
"signal": "number 1–5 (required)",
"created_at": "timestamptz (optional input for historical imports; normalized on write)",
"updated_at": "timestamptz (auto)",
"deleted_at": "timestamptz (optional soft-delete timestamp; omit to leave deletion status unchanged)"
}CI/CD
- GitHub 操作 --lint、测试（85%的业务逻辑覆盖率）、机密扫描、构建
- 请释放 --传统的基于提交的语义版本控制
- 布料+棉绒 --强制执行AI归因脚注
- 左撇子 --git钩子用于提交消息验证
许可证
PolyForm Shield 1.0.0