Replace query-token MCP setup with a safe supported contract and tool export

[aviyashchin]

Job

Export Ghostshell's existing tool registry as a deterministic public MCP manifest and document one safe supported connection path without exposing bearer credentials in URLs.

Current evidence (2026-07-26)

• Current main SHA is 6cbc5ec7f5e98d9dffb0029b0e2ba1665549f2f8.
• The repository has the server/tool registry but no deterministic tool-manifest exporter or checked discovery artifact.
• README recommends hosted SSE with ?token=YOUR_TOKEN, includes query-token fallback, and links to stale Fern docs.

Exit criterion

• A deterministic exporter emits a versioned manifest containing tool name, description, input schema, source revision, generation time, transport, and authentication metadata without secrets.
• CI proves a second generation is byte-stable apart from explicitly normalized generated metadata and detects registry/manifest drift.
• Local stdio is documented and smoke-tested as the baseline safe connection path.
• Public docs no longer recommend query-string bearer tokens or stale Fern URLs.
• Any hosted transport claimed as supported has a real protocol/auth smoke test; otherwise it is explicitly marked experimental and split into a follow-up issue.

Prerequisites

• A non-production test credential is required only for a hosted authenticated smoke test; manifest export and stdio proof have no credential prerequisite.
• Work from a clean worktree based on the then-current origin/main.

Files in scope

• Existing server/tool registry and focused tests
• Existing smoke_mcp.py or equivalent repository smoke path
• A narrow export script and generated manifest location
• README and connection examples

Reuse first

Derive the manifest directly from the existing registered tools and reuse the current MCP server/smoke path. Do not hand-maintain a second tool list or add a new gateway.

Out of scope

• New MCP tools
• A general OAuth platform
• Docs-site artifact assembly, which belongs to public docs #37
• Supporting multiple hosted transports without tests

Stop condition

If the current hosted transport cannot authenticate without URL credentials, do not label it production-supported. Ship the deterministic export and stdio contract, and open a separate bounded hosted-auth issue.

[aviyashchin]

Draft PR #15 is ready for review: #15

Validated at 1f754461711fa82c62508e01951815c87c14c392:

• 70 tests pass; Ruff and mypy pass
• real stdio MCP initialize + tools/list returns all 15 tools
• repeated export is byte-identical (b653818071c082574749a8617b7229b8b6a40a086b4fd2fd5fccdb3d548247c6)
• manifest read-back proves registry source revision 1654c170fcbbeee4c6f489c35f74fe8b6df5d624
• public setup contains no query-token recommendation or stale Fern URL

Hosted SSE remains experimental. Credentialed deployment proof is split into #14. This is a draft only; nothing has been merged or deployed.

[aviyashchin]

Validated draft PR #15 is ready for review at ddea125cb939e1f44cb7a3b0270a3ccb168560f3. Agents get a deterministic source-owned 15-tool manifest and safe stdio setup; stale query-token guidance is retired. Local proof and exact-head CI are green; nothing was merged or deployed.

[aviyashchin]

Parked under the approved draft-only boundary. PR #15 at ddea125cb939e1f44cb7a3b0270a3ccb168560f3 passes 71 tests, lint, typecheck, deterministic export, and real stdio discovery; the source manifest is not available to downstream docs until merge. Human action needed: review and authorize merging PR #15.

[aviyashchin]

Ready for independent review: #15. Customer benefit: agents can discover all 15 MCP tools and connect through the supported environment-authenticated stdio path without query tokens. Exact head a597b2c; 71 tests and all required checks are green. No merge or deployment performed.

[aviyashchin]

Updated review-ready PR #15 at exact head 6cf88dd after independent review. The revision closes three validation gaps: recursive shared-source provenance, a bounded stdio smoke timeout, and non-persisted CI checkout credentials. Fresh local proof: 74 tests, Ruff, mypy, manifest regeneration/diff, and the real 15-tool stdio smoke all pass. CI and independent re-review are now running. No merge performed.

[aviyashchin]

Review-ready evidence refreshed for PR #15 at 9ce1fcf1568ae28757d10a56e40b7eeca5ade13e. Clean Python 3.11: 75 tests, Ruff, mypy, deterministic manifest, and real 15-tool stdio handshake pass with MCP 1.29.0. GitHub lint/test/validate-mcp and previews are green; CodeRabbit approved. No merge performed.

[aviyashchin]

Final review-ready head is now 017733ffc855713bab729e5e026d719b5dbc0dd4. The remaining valid style feedback was addressed without changing production behavior: both new MCP test modules now follow the repo-required class-based pytest pattern, and the protocol test is natively async. Fresh clean Python 3.11 proof: 75 tests, Ruff, mypy, deterministic manifest, and real 15-tool stdio handshake pass with MCP 1.29.0. All CI, CodeRabbit, Seer, and preview checks are green. Single remaining action: assign an independent human reviewer. No merge performed.

[aviyashchin]

Closeout: PR #15 and post-squash provenance refresh #16 are merged. Main revision 7ede62f has green default-branch CI; the public export contains 15 tools, supported stdio transport, and environment-delivered bearer auth with no query-token setup. Lesson preserved in README/CLAUDE: validate the real MCP initialize/tools-list exchange, and regenerate revision-bearing exports after squash merge.