polish-docs-meta

When to Use

• Server implementation is functionally complete (tools, resources, prompts, services all working)
• bun run devcheck passes, tests pass
• You're preparing for first commit, first release, or making the repo public
• User says "polish", "polish docs", "finalize", "make it ship-ready", "clean up docs", or similar
• Re-running after adding/removing tools, resources, or other surface area changes

Prefer running after implementation is complete, but safe to re-run at any point — steps are idempotent.

Prerequisites

• All tools/resources/prompts implemented and registered
• bun run devcheck passes
• Tests pass (bun run test)

If these aren't met, address them first.

Steps

1. Audit the Surface Area

Read all tool, resource, and prompt definitions. Build a mental model of what the server actually does — names, descriptions, input/output shapes, auth scopes. This inventory drives every document below.

Read:

• src/index.ts (what's registered in createApp())
• All files in src/mcp-server/tools/definitions/
• All files in src/mcp-server/resources/definitions/
• All files in src/mcp-server/prompts/definitions/
• All files in src/services/ (if any)
• src/config/server-config.ts (if any)

Capture: tool count, resource count, prompt count, service count, required env vars.

2. README.md

Read references/readme.md for structure and conventions. If README.md doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't rewrite sections that are already accurate.

The header tagline (<p><b>...</b></p>) must match the package.json description.

3. Agent Protocol (CLAUDE.md / AGENTS.md)

Update the project's agent protocol file to reflect the actual server.

Read references/agent-protocol.md for the full update checklist, then review the current file and address what's stale or missing:

• If a "First Session" onboarding block is still present and onboarding is complete, it can go
• If example patterns still use generic/template names (e.g., searchItems, itemData), replace with real definitions from this server
• If server-specific skills were added, update the skills table
• Verify the structure diagram matches the actual directory layout
• If custom scripts were added to package.json, update the commands table

4. .env.example

Compare .env.example against the server config Zod schema. Add any missing server-specific vars with a comment and default (if any). Remove vars for features that no longer exist. Group by category. Preserve existing framework vars that are still relevant.

5. package.json Metadata

Check for empty or placeholder metadata fields. Read references/package-meta.md for which fields matter and why. Fill in anything still missing — skip fields that are already correct.

Key fields: description, repository, author, homepage, bugs, keywords.

description is the canonical source. Every other surface (README header, server.json, Dockerfile OCI label, GitHub repo description) derives from it. Write it here first, then propagate.

6. server.json

Read references/server-json.md for the official MCP server manifest schema. If server.json doesn't exist, create it from the surface area audit. If it exists, diff against current state and update stale fields.

Key sync points:

• $schema set to https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json
• name matches mcpName from package.json (reverse-domain: io.github.{owner}/{repo})
• version matches package.json version (in all three places: top-level + each package entry)
• description matches package.json description
• environmentVariables reflect the server config Zod schema — server-specific required vars in both entries, transport vars only in HTTP entry
• Two package entries: one for stdio, one for HTTP (if both transports supported)

7. GitHub Repository Metadata

Sync the GitHub repo with package.json using the gh CLI. Skip if the repo isn't hosted on GitHub or gh isn't available.

Description:

gh repo edit <owner>/<repo> --description "<package.json description>"

Topics ↔ Keywords:

Compare GitHub topics (gh repo view --json repositoryTopics) against package.json keywords. They should be the union — add any that exist in one but not the other:

• Missing from GitHub → gh repo edit --add-topic <topic>
• Missing from package.json → add to keywords array

Common keywords shared across MCP servers (e.g., mcp, mcp-server, model-context-protocol, typescript) should appear in both. Domain-specific keywords should also be present in both.

8. bunfig.toml

Verify a bunfig.toml exists at the project root. If not, create one:

[install]
auto = "fallback"
frozenLockfile = false

[run]
bun = true

9. CHANGELOG.md

If CHANGELOG.md doesn't exist, create it with an initial entry. If it exists, verify the latest entry reflects the current state:

# Changelog

## 0.1.0 — YYYY-MM-DD

Initial release.

### Added
- [list tools, resources, prompts, key capabilities]

Use a concrete version and date. Never [Unreleased].

10. LICENSE

Confirm a license file exists. If not, ask the user which license to use (default: Apache-2.0, matching the scaffolded package.json). Create the file.

11. Dockerfile

If a Dockerfile exists, verify the OCI labels and runtime config match the actual server:

• org.opencontainers.image.title matches the package name
• org.opencontainers.image.description matches package.json description
• org.opencontainers.image.source points to the real repository URL (add if missing)
• Log directory path in mkdir and LOGS_DIR uses the correct server name

If no Dockerfile exists and the server is deployed via HTTP transport, consider scaffolding one — the template is available via npx @cyanheads/mcp-ts-core init.

12. docs/tree.md

Regenerate the directory structure:

bun run tree

Review the output for anything unexpected (leftover files, missing directories).

13. Final Verification

Run the full check suite one last time:

bun run devcheck
bun run test

Both must pass clean.

Checklist

• Surface area audited — tool/resource/prompt/service inventory built
• README.md accurate — tool/resource tables, config, descriptions match actual code
• Agent protocol file accurate — no stale template content, real examples, structure matches reality
• .env.example in sync with server config schema
• package.json metadata complete (description, mcpName, repository, author, keywords, engines, packageManager)
• server.json matches official MCP schema, versions synced, env vars current
• GitHub repo description matches package.json description; topics ↔ keywords in sync
• bunfig.toml present
• CHANGELOG.md exists with current entry
• LICENSE file present
• Dockerfile OCI labels and runtime config accurate (if present)
• docs/tree.md regenerated
• bun run devcheck passes
• bun run test passes