molecule-ai/molecule-core
49
0
Fork 2
Code Issues 145 Pull Requests 157 Actions 6 Packages Projects Releases Wiki Activity

RFC: OpenAPI spec + generated clients (kill MCP/CLI/SDK hand-written HTTP wrapper drift) #1706

New Issue
Open
opened 2026-05-23 06:33:19 +00:00 by hongming · 0 comments
hongming commented 2026-05-23 06:33:19 +00:00
Owner
Copy Link
Copy Source

Summary

The platform HTTP API in workspace-server/internal/handlers/*.go is the single source of truth for business logic. But four hand-written clients reimplement the HTTP wrapper layer with drifted auth + retry + error mapping.

Client HTTP wrapper Auth
canvas/src/lib/api.ts api.get/patch/post/del Bearer + X-Molecule-Org-Slug
molecule-mcp-server/src/api.ts apiCall(method, path) none (drifted; CLAUDE.md says MOLECULE_API_KEY required, code didn't read it)
molecule-cli/internal/client/platform.go getInto/postInto/delete none
molecule-sdk-python/molecule_agent/client.py httpx Bearer + X-Molecule-Org-Id

Problems

  1. 3 different auth shapes across 4 clients
  2. MCP server MOLECULE_API_KEY documented-but-not-read — silent auth bypass against prod
  3. No OpenAPI spec anywhere in the org — every client hand-typed against Go handler signatures
  4. 4 retry/error implementations — no consistency
  5. Adding an endpoint requires 4 hand edits; easy to miss one

Proposed shape

  1. OpenAPI 3.1 spec generated from Go handlers (swaggo or huma). Emit workspace-server/openapi.yaml at build.
  2. Generate clients from spec:
    • TS (canvas + MCP): openapi-typescript-codegen
    • Python SDK: openapi-python-client
    • Go CLI: oapi-codegen
  3. Hand-write only an AuthProvider shim per client (~20 lines)
  4. CI gate: PR fails if regenerated client doesn't match committed

Phases

  • Phase 1: Add swaggo annotations to one handler (schedules.go) + make openapi-spec target + commit workspace-server/openapi.yaml — prove pipeline
  • Phase 2: Annotate remaining handlers (workspaces/agents/secrets/files/memory/channels/plugins)
  • Phase 3: Generate TS client; replace MCP api.ts hand wrapper (keep auth shim)
  • Phase 4: Generate Go client; replace CLI platform.go
  • Phase 5: Generate Python client; replace SDK HTTP layer
  • Phase 6: canvas — types-only regen (keep their fetch wrapper for browser session-cookie path)
  • Phase 7: CI gate

Non-goals

  • No backend handler rewrites
  • Don't unify auth in this RFC — follow-up after shape is shared
  • canvas keeps custom browser fetch wrapper (session-cookie path is special)

Refs

  • canvas: molecule-core/canvas/src/lib/api.ts
  • MCP: molecule-mcp-server/src/api.ts
  • CLI: molecule-cli/internal/client/platform.go
  • Python SDK: molecule-sdk-python/molecule_agent/client.py
  • Backend handlers SSOT: molecule-core/workspace-server/internal/handlers/*.go
  • Backend router: molecule-core/workspace-server/internal/router/router.go:376-388
## Summary The platform HTTP API in `workspace-server/internal/handlers/*.go` is the single source of truth for business logic. But **four hand-written clients** reimplement the HTTP wrapper layer with drifted auth + retry + error mapping. | Client | HTTP wrapper | Auth | |---|---|---| | `canvas/src/lib/api.ts` | `api.get/patch/post/del` | Bearer + `X-Molecule-Org-Slug` | | `molecule-mcp-server/src/api.ts` | `apiCall(method, path)` | **none** (drifted; CLAUDE.md says `MOLECULE_API_KEY` required, code didn't read it) | | `molecule-cli/internal/client/platform.go` | `getInto/postInto/delete` | **none** | | `molecule-sdk-python/molecule_agent/client.py` | httpx | Bearer + `X-Molecule-Org-Id` | ## Problems 1. 3 different auth shapes across 4 clients 2. MCP server `MOLECULE_API_KEY` documented-but-not-read — silent auth bypass against prod 3. No OpenAPI spec anywhere in the org — every client hand-typed against Go handler signatures 4. 4 retry/error implementations — no consistency 5. Adding an endpoint requires 4 hand edits; easy to miss one ## Proposed shape 1. OpenAPI 3.1 spec generated from Go handlers (swaggo or huma). Emit `workspace-server/openapi.yaml` at build. 2. Generate clients from spec: - TS (canvas + MCP): `openapi-typescript-codegen` - Python SDK: `openapi-python-client` - Go CLI: `oapi-codegen` 3. Hand-write only an `AuthProvider` shim per client (~20 lines) 4. CI gate: PR fails if regenerated client doesn't match committed ## Phases - Phase 1: Add swaggo annotations to one handler (`schedules.go`) + `make openapi-spec` target + commit `workspace-server/openapi.yaml` — prove pipeline - Phase 2: Annotate remaining handlers (workspaces/agents/secrets/files/memory/channels/plugins) - Phase 3: Generate TS client; replace MCP `api.ts` hand wrapper (keep auth shim) - Phase 4: Generate Go client; replace CLI `platform.go` - Phase 5: Generate Python client; replace SDK HTTP layer - Phase 6: canvas — types-only regen (keep their fetch wrapper for browser session-cookie path) - Phase 7: CI gate ## Non-goals - No backend handler rewrites - Don't unify auth in this RFC — follow-up after shape is shared - canvas keeps custom browser fetch wrapper (session-cookie path is special) ## Refs - canvas: `molecule-core/canvas/src/lib/api.ts` - MCP: `molecule-mcp-server/src/api.ts` - CLI: `molecule-cli/internal/client/platform.go` - Python SDK: `molecule-sdk-python/molecule_agent/client.py` - Backend handlers SSOT: `molecule-core/workspace-server/internal/handlers/*.go` - Backend router: `molecule-core/workspace-server/internal/router/router.go:376-388`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/ci
CI/CD pipeline issues
 kind/infrastructure
Infrastructure-related issues
 merge-queue
Ready for serialized Gitea merge queue
 merge-queue-hold
Temporarily hold PR in merge queue
 platform/go
Go platform test issues
 release-blocker
Blocks the staging→main promotion / a release
 release-test
security
test-label-sre
tier:high
High risk per dev-sop §SOP-6 — ceo only, 24h cooldown
 tier:low
Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve
 tier:medium
Medium risk per dev-sop §SOP-6 — managers/ceo can approve
 triage-test
test
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#1706
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?