// Finalize documentation and project metadata for a ship-ready release. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
| name | polish-docs-meta |
| description | Finalize documentation and project metadata for a ship-ready release. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work. |
| metadata | {"author":"cyanheads","version":"1.0","type":"workflow"} |
bun run devcheck passes, bun test passesPrefer running after implementation is complete, but safe to re-run at any point — steps are idempotent.
bun run devcheck passesbun test passesIf these aren't met, address them first.
Read the registered definitions. Build a mental model of what the server actually exposes — names, descriptions, input/output shapes, auth scopes. This inventory drives every document below.
Read:
src/mcp-server/tools/definitions/index.ts (the allToolDefinitions barrel)src/mcp-server/tools/definitions/git-*.tool.tssrc/mcp-server/resources/definitions/index.tssrc/mcp-server/resources/definitions/git-working-directory.resource.tssrc/mcp-server/prompts/definitions/index.tssrc/mcp-server/prompts/definitions/git-wrapup.prompt.tssrc/config/index.ts (Zod config schema)src/services/git/core/IGitProvider.ts (provider contract)Capture: tool count (expected ~29), resource count, prompt count, git provider capabilities, required env vars.
Compare README content against the audit. Update tool/resource/prompt tables, env var lists, badges, and descriptions to match actual surface area. Don't rewrite sections that are already accurate.
Specific sync points:
package.json versionTOOL_DESCRIPTIONsrc/config/index.ts with current defaults[Hono](https://hono.dev/), [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk), etc.) are on first mentionAGENTS.md is a symlink to CLAUDE.md — edit only CLAUDE.md.
Review against reality:
src/createToolHandler, ToolLogicDependencies, IGitProvider) — not outdated signaturespackage.json versionKeep the diff minimal — change what's stale, leave what's accurate.
.env.exampleCompare .env.example against the src/config/index.ts Zod schema. Add any missing vars with a comment and default. Remove vars for features that no longer exist. Group by category (Transport, Auth, Storage, Git, Telemetry) matching the schema's layout.
Categories to cover:
MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, MCP_HTTP_HOST, MCP_HTTP_PATHMCP_AUTH_MODE, MCP_AUTH_SECRET_KEY, OAUTH_ISSUER_URL, OAUTH_AUDIENCE, OAUTH_JWKS_URISTORAGE_PROVIDER_TYPE, STORAGE_FILESYSTEM_PATHGIT_PROVIDER, GIT_SIGN_COMMITS, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, GIT_BASE_DIR, GIT_MAX_COMMAND_TIMEOUT_MS, GIT_MAX_BUFFER_SIZE_MB, GIT_WRAPUP_INSTRUCTIONS_PATHOTEL_ENABLED, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINTpackage.json MetadataCheck for empty or placeholder fields. Key fields:
| Field | Source of truth |
|---|---|
description | Canonical — every other surface derives from it |
version | Semver, matches server.json and CHANGELOG.md headline |
mcpName | Reverse-domain: io.github.cyanheads/git-mcp-server |
repository.url | git+https://github.com/cyanheads/git-mcp-server.git |
bugs.url | https://github.com/cyanheads/git-mcp-server/issues |
homepage | https://github.com/cyanheads/git-mcp-server#readme |
keywords | Union with GitHub topics (see step 7) |
engines | bun >=1.2.0, node >=20.0.0 |
packageManager | Pinned bun version |
author | cyanheads <casey@caseyjhand.com> |
license | Apache-2.0 |
description is the canonical source. Every other surface (README header, server.json, GitHub repo description) derives from it. Write it here first, then propagate.
server.jsonDiff against current state and update stale fields. Key sync points:
$schema set to the current MCP server manifest schema URLname matches mcpName from package.jsonversion matches package.json version (in all places: top-level + each packages[].version)description matches package.json descriptionenvironmentVariables reflect src/config/index.ts — server-specific required vars in both entries, transport vars only in HTTP entrySync the GitHub repo with package.json using gh. Skip if gh isn't available.
Description:
gh repo edit cyanheads/git-mcp-server --description "$(jq -r .description package.json)"
Topics ↔ Keywords:
Compare GitHub topics against package.json keywords. They should be the union — add any that exist in one but not the other.
gh repo view --json repositoryTopics -q '.repositoryTopics[].name'
jq -r '.keywords[]' package.json
gh repo edit --add-topic <topic>package.json → add to keywords arrayCommon keywords across MCP servers (mcp, mcp-server, model-context-protocol, typescript) should appear in both. Domain-specific keywords (git, version-control, branch, etc.) should also be present in both.
CHANGELOG.mdThis repo uses a monolithic changelog in Keep a Changelog format. Conventions:
## v<version> - <YYYY-MM-DD> header with a concrete version and date — never [Unreleased]### Added, ### Changed, ### Fixed, ### Removed, ### Security### Breaking header`git_merge`), PR/issue numbers ((#42)), and user-visible commandsBefore shipping a release, verify the top entry is current, dated, and complete. Hand-editing is expected — no build step.
bunfig.tomlVerify bunfig.toml exists at the project root. Expected contents:
[install]
auto = "fallback"
frozenLockfile = false
[run]
bun = true
LICENSEConfirm the LICENSE file exists and matches package.json license field (Apache-2.0).
docs/tree.mdRegenerate the directory structure:
bun run tree
Review the output for anything unexpected (leftover scaffolding files, missing directories, stray dist artifacts).
Run the full check suite one last time:
bun run devcheck
bun test
Both must pass clean.
README.md accurate — tool tables, config, descriptions match actual codeCLAUDE.md accurate — no stale content, real examples, structure matches reality; AGENTS.md symlink intact.env.example in sync with src/config/index.tspackage.json metadata complete and versionedserver.json schema + versions + env vars current; matches package.jsonpackage.json; topics ↔ keywords in syncbunfig.toml presentCHANGELOG.md has a concrete-dated entry for the release (Keep a Changelog format)LICENSE file presentdocs/tree.md regeneratedbun run devcheck passesbun test passesExercise git tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify the MCP surface.
Investigate, adopt, and verify dependency updates. Captures what changed, understands why, cross-references against the codebase, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
Ship a release end-to-end across every registry this project targets (npm, MCP Registry). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Halts and alerts the user on the first failure.
File a bug or feature request against this repository (cyanheads/git-mcp-server) using the `gh` CLI. Use for tool logic bugs, git provider misbehavior, transport issues, auth/config problems, or new feature proposals.