Create develop-mcp-app skill for SDK+MCP+CLI scaffolding

[krisrowe]

Problem

Building a new MCP-powered tool requires repeating the same scaffolding every time: SDK+MCP+CLI three-layer architecture, pyproject.toml with entry points, CLAUDE.md with @ imports, .gemini/settings.json, CONTRIBUTING.md linking to the canonical pattern doc, test fixtures with env var isolation, .gitignore. The dominant time cost for new tools is wiring, not features.

The gapp:deploy skill covers Cloud Run deployment but is not the right place for generic app architecture guidance. There is no skill that covers the base SDK+MCP+CLI pattern independent of deployment target. Similarly, user management is an mcp-app framework capability but the only skill for it is gapp:user-management, which frames it as a post-deploy gapp concern.

Proposed solution

Create a develop-mcp-app skill in the skills marketplace (coding/develop-mcp-app/SKILL.md) that provides guidance for building MCP tools following the SDK-first architecture, covering the full lifecycle from local stdio tools through cloud-deployed multi-user apps.

What the skill covers

Base architecture (all MCP tools):

1. Repository structure — sdk/, mcp/, cli/ layers, pyproject.toml with entry points and optional extras, packaging for pip install and pipx install from git URLs.

2. SDK-first pattern — all business logic in sdk/, MCP tools and CLI commands are one-liner calls to SDK. Link to framework/README.md.

3. MCP framework — official MCP Python SDK (from mcp.server.fastmcp import FastMCP). Link to mcp-framework.md.

4. Agent context setup — CLAUDE.md with @ imports, .gemini/settings.json, .gitignore. Reference setup-agent-context.

5. Documentation conventions — README.md (usage) vs. CONTRIBUTING.md (architecture, constraints). CONTRIBUTING.md links to canonical framework doc.

6. Testing — sociable unit tests on the SDK, env var isolation, no mocks. Reference develop-unit-tests.

7. SDK as lightweight distribution — optional extras pattern.

Cloud / multi-user layer (mcp-app-based tools):

8. Local vs. cloud decision — when SDK+MCP+CLI is sufficient (local stdio tools) vs. when to add mcp-app for HTTP transport, JWT auth, and per-user data isolation.

9. mcp-app configuration — mcp-app.yaml, middleware selection (JWT, credential-proxy), store selection (filesystem, custom), tool discovery, admin endpoint setup.

10. User management — registering users, listing users, revoking access, issuing tokens. This is an mcp-app framework capability accessible independent of deployment target.

11. Deployment handoff — clean boundary where mcp-app concerns end and deployment (e.g., gapp:deploy) begins.

What the skill does NOT cover

• Cloud Run deployment lifecycle (gapp:deploy)
• Terraform, secrets management, CI/CD (gapp)
• Plugin/extension packaging (plugin-creator)

Background

This consolidates what was previously scattered across gapp:develop (tightly coupled to Cloud Run) and gapp:user-management (framed as post-deploy). The code-level decoupling happened in gapp#7 (auth moved to app-user, absorbed by mcp-app). This issue completes the decoupling at the skills/tooling level.

Skill modes

• Greenfield — scaffold a new repo from scratch
• Review — audit an existing repo against canonical patterns, report drift

Open questions

• Should mcp-app user management also be exposed as MCP tools on the mcp-app server itself (so agents can manage users directly), or is a skill that guides CLI usage sufficient?
• Does the skill need sub-skills or should it be one document with sections?

Work breakdown

• Create coding/develop-mcp-app/SKILL.md in the skills marketplace
• Reference canonical docs: framework/README.md, mcp-framework.md, develop-unit-tests, setup-agent-context
• Include mcp-app configuration and user management guidance
• Define clean handoff point to gapp:deploy
• Publish to marketplace and verify discovery via aicfg skills list

Related

• framework/README.md — canonical architecture guide
• gapp#7 (closed) — decoupled auth/user management from gapp runtime