xfy/yggdrasil
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
yggdrasil/.scratch/mcp-server/issues/T7-verification-docs.md
xfy ef4c4ee8ed docs(mcp): CHANGELOG + .env.example + AGENTS.md + DEPLOYMENT（T7） 
- CHANGELOG：[Unreleased]/Added 记录 MCP 服务器功能（传输/认证/作用域/工具面/加固/配置/依赖/环境变量）。
- .env.example：新增 MCP_TOKEN_ENC_KEY（必填，openssl rand -hex 32）+ RATE_LIMIT_MCP_PER_SEC/_BURST。
- AGENTS.md：新增「MCP Server」章节（传输/认证/令牌存储/作用域/工具组合模式/feature 门控/配置生成）+ Key Directories 加 src/mcp/ + 迁移数 14→17。
- DEPLOYMENT.md：必设变量表加 MCP_TOKEN_ENC_KEY；新增「/mcp 端点」反代说明（catch-all 代理/Origin 白名单取自 APP_BASE_URL/bearer 不经 cookie/独立限流桶）。

实时客户端冒烟测试延后到用户环境（需运行中的 DB + MCP_TOKEN_ENC_KEY + 真实 MCP 客户端）；
机制已由 T1 探针验证，集成路径在工单 T7 记录了用户侧步骤。
2026-07-28 12:01:23 +08:00

2.1 KiB
Raw Blame History

T7 — Integration verification + docs

Blocking edges

  • Blocks: nothing (terminal ticket).
  • Blocked by: T2 (UI), T6 (hardening).

Target files

  • docs/CHANGELOG.md, .env.example, AGENTS.md (architecture note), docs/DEPLOYMENT.md.

Change

  1. Manual smoke test against a running instance with a real client (Claude Code preferred, Cursor/Cline as available): mint a read token → connect → search_posts → resources/read; mint a write token → create_post → confirm it appears in the web admin with rendered content_html; mint an admin token → run_code. Confirm invalid token / bad Origin / scope-mismatch are rejected.
  2. Update docs/CHANGELOG.md (Keep a Changelog): feat(mcp): ... entry.
  3. .env.example: document MCP_TOKEN_ENC_KEY + MCP rate-limit vars.
  4. AGENTS.md: add a short MCP section (transport, auth model, scope mapping, the /mcp route, feature-gating note) under the existing architecture structure.
  5. docs/DEPLOYMENT.md: note that /mcp must pass through the reverse proxy and that MCP_TOKEN_ENC_KEY is required for the feature.

Status (2026-07-28)

  • Docs (CHANGELOG / .env.example / AGENTS.md / DEPLOYMENT.md): ✓ done.
  • make lint equivalent: ✓ cargo clippy --all-features -- -D warnings clean.
  • Live-client smoke test DEFERRED to user: requires a running DB instance + MCP_TOKEN_ENC_KEY env + a real MCP client (Claude Code/Cursor). The mechanism is proven (T1 probe verified tools/list, tools/call, Origin→403, bearer→principal end-to-end against rmcp directly); the remaining step is exercising it against the integrated app with a seeded token. Steps for the user:
    1. Set MCP_TOKEN_ENC_KEY=$(openssl rand -hex 32) + restart the app (runs migration 017).
    2. In /admin/mcp, mint a read token → copy the Claude Code config → claude mcp add.
    3. Verify search_posts returns published posts; mint a write token → create_post → confirm it appears in the web admin with rendered content_html.
    4. Confirm invalid token → 401, scope mismatch → invalid_request.