Skip to content

feat(mcp): GET /api/v1/mcp/skill — env-customized Agent Skill download (#2714) - #2728

Merged
os-zhuang merged 2 commits into
mainfrom
feat/mcp-skill-endpoint
Jul 10, 2026
Merged

os-zhuang merged 2 commits into
mainfrom
feat/mcp-skill-endpoint

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

#2714 Phase 1 — the framework dependency called out in objectstack-ai/objectui#2363: renderSkillMarkdown() (the ONE generic skill, ADR-0036 Amendment C) had no HTTP outlet.

What

GET /api/v1/mcp/skill serves the environment-customized SKILL.md as text/markdown (+ content-disposition: inline; filename="SKILL.md", cache-control: no-store — same reasoning as /discovery, cloud#152).

  • Public like /discovery: the content is generic agent instructions plus a URL the caller already knows — no schema, no tenant data.
  • Gates mirror /mcp: 404 when OS_MCP_SERVER_ENABLED=false (nothing advertised), 501 when the MCP plugin isn't loaded, 405 (+Allow) for non-GET.
  • Env URL resolution: auth service's canonical getMcpResourceUrl() first, request-host (host + x-forwarded-proto) fallback, documented placeholder last.
  • MCPServerRuntime.renderSkill() exposes the renderer through the registered 'mcp' service, so the runtime keeps zero dependency on @objectstack/mcp (same duck-typed seam as handleHttpRequest).
  • Implementation note: raw text rides the dispatcher's result stream channel (single-chunk) — the response channel JSON-encodes bodies unconditionally, which would have shipped a quoted string.

Verification

  • Unit: 5 new dispatcher tests (200/content/URL-preference, opt-out 404, no-service 501, 405+Allow, anonymous access); runtime 477 ✓, mcp 64 ✓.
  • Live on showcase: raw markdown body (not JSON-quoted), correct headers, http://localhost:3210/api/v1/mcp injected into the Connect section from the request host.

Refs #2714, objectstack-ai/objectui#2363.

🤖 Generated with Claude Code

#2714)

renderSkillMarkdown had no HTTP outlet. Serve it from the runtime dispatcher
as text/markdown via the raw stream channel (the response channel JSON-encodes
bodies), public like /discovery, 404 when the MCP surface is opted out, 501
without the mcp service; URL from auth getMcpResourceUrl() with request-host
fallback. Live-verified on showcase (raw markdown + headers + URL injection).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jul 10, 2026 3:53am

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation tests tooling size/m labels Jul 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/mcp, @objectstack/runtime.

21 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/ai/actions-as-tools.mdx (via @objectstack/mcp)
  • content/docs/ai/agents.mdx (via @objectstack/mcp)
  • content/docs/ai/index.mdx (via @objectstack/mcp)
  • content/docs/ai/natural-language-queries.mdx (via @objectstack/mcp)
  • content/docs/api/index.mdx (via @objectstack/mcp, @objectstack/runtime)
  • content/docs/api/wire-format.mdx (via @objectstack/runtime)
  • content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
  • content/docs/concepts/north-star.mdx (via packages/runtime)
  • content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
  • content/docs/deployment/environment-variables.mdx (via @objectstack/mcp)
  • content/docs/deployment/index.mdx (via @objectstack/runtime)
  • content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
  • content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
  • content/docs/deployment/vercel.mdx (via @objectstack/runtime)
  • content/docs/permissions/authentication.mdx (via @objectstack/runtime)
  • content/docs/plugins/packages.mdx (via @objectstack/mcp, @objectstack/runtime)
  • content/docs/protocol/knowledge.mdx (via @objectstack/mcp)
  • content/docs/protocol/objectos/http-protocol.mdx (via @objectstack/runtime)
  • content/docs/protocol/objectos/index.mdx (via @objectstack/runtime)
  • content/docs/protocol/objectos/lifecycle.mdx (via @objectstack/runtime)
  • content/docs/releases/implementation-status.mdx (via @objectstack/mcp, @objectstack/runtime)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

@os-zhuang
os-zhuang merged commit bc26360 into main Jul 10, 2026
15 of 16 checks passed
@os-zhuang
os-zhuang deleted the feat/mcp-skill-endpoint branch July 10, 2026 03:52

This branch was successfully deployed

1 active deployment
Preview — 5debfe91 Deployed Jul 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/m tests tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant