agent.md — getmcp Codebase Guide

For the complete specification (schemas, transformation rules, config formats, research appendix), see SPECIFICATION.md.

Project Summary

getmcp is a universal installer and configuration tool for MCP (Model Context Protocol) servers across all AI applications. Every AI app (Claude Desktop, VS Code, Cursor, Goose, Windsurf, Zed, etc.) uses a different config format for MCP servers — different root keys, field names, file formats, and conventions. getmcp solves this by defining a single canonical format (aligned with the official MCP registry schema), then using generators to transform it into each app's native format. A registry of popular servers, a CLI for automated installation, and a web directory complete the toolchain.

Architecture Overview

This is a TypeScript monorepo (npm workspaces, ESM-only, Node >= 22.17) with 5 packages:

@getmcp/cli -----> @getmcp/generators -----> @getmcp/core
            \----> @getmcp/registry   -----> @getmcp/core
@getmcp/web -----> @getmcp/core + @getmcp/generators + @getmcp/registry

Tech stack: TypeScript 5.7+, Zod 4.0+, Vitest 3.0+, Next.js 15.3+ (web), Tailwind CSS 4.0+ (web), @clack/prompts (CLI). Linting/Formatting: oxlint + oxfmt, enforced via lefthook pre-commit hook.

See .agents/docs/SPECIFICATION.md Section 3 for the full architecture breakdown.

Key Concepts

• Canonical Format: Single format aligned with the official MCP registry schema (root key mcpServers). Stdio: command, args, env, cwd, timeout, description. Remote: url, transport, headers, timeout, description. Transport auto-inferred from URL.
• Generators: Extend BaseGenerator (packages/generators/src/base.ts), implement generate() to transform canonical → app-native format. Each implements detectInstalled() for platform-specific app detection.
• Registry: Map<string, InternalRegistryEntry> keyed by official reverse-DNS name (e.g. io.github.github/github-mcp-server), with search and filtering functions. getServer() is ID-only; use getServerBySlug() for slug lookups (web URLs).
• CLI: Auto-detects installed apps, prompts for env vars, generates app-specific configs, and merges into existing files (never overwrites). Tracks installations in getmcp-lock.json.
• Design Principles: (1) Never overwrite (2) Canonical format as single source of truth (3) Auto-detect apps (4) Platform-aware path resolution (5) Schema-validated via Zod

See file-map.md for the complete file-by-file reference.

Common Tasks

MCP server registry

Server data is synced from the official MCP registry via packages/registry/scripts/sync.ts. To add a new server, submit it to the official registry — getmcp syncs automatically via the daily GitHub Actions workflow.

Adding a new generator (supporting a new AI app)

1. Add the new app ID to the AppId enum in packages/core/src/schemas.ts
2. Create packages/generators/src/<app-name>.ts extending BaseGenerator
3. Implement generate() with the app's field mappings; override serialize() if non-JSON
4. Set the app property with AppMetadata (id, name, configFileName, configPaths per platform, docsUrl)
5. Register the generator in packages/generators/src/index.ts
6. Add stdio + remote tests in packages/generators/tests/generators.test.ts
7. Add detection paths in packages/cli/src/detect.ts if the app has a known config file location
8. Update packages/web/src/components/ConfigViewer.tsx to include the new app tab

Modifying an existing generator's transformation rules

1. Locate the generator file: packages/generators/src/<app-name>.ts
2. Review its generate() method to understand current field mappings
3. Make changes and run npx vitest packages/generators to validate
4. Cross-reference with .agents/docs/SPECIFICATION.md Section 5 and Section 10 for the app's official format

Adding a CLI command

1. Create packages/cli/src/commands/<command>.ts
2. Wire it into packages/cli/src/bin.ts argument dispatch using dynamic import()
3. Add command aliases in packages/cli/src/utils.ts (COMMAND_ALIASES map) if the command should have shorthand names
4. Handle prompt cancellation using the exitIfCancelled() helper from packages/cli/src/utils.ts
5. Add tests in packages/cli/tests/

Post-Implementation Documentation Check

After every code implementation (new feature, new command, new file, bug fix, refactor, etc.), review the following documentation files and update any that are affected:

This is not optional — documentation drift causes confusion and wastes time. Treat it as part of completing the implementation.

Testing

• 720 tests across 30 test files
• Run all tests: npx vitest (from repo root)
• Run per-package: npx vitest packages/core, npx vitest packages/generators, etc.
• Test locations:
  • packages/core/tests/ — schema validation (including RegistrySource, RegistryCredential, RegistryAuthMethod), type guards, transport inference, ProjectManifest
  • packages/generators/tests/ — all 19 generators (stdio + remote + multi-server + serialization + detectInstalled)
  • packages/registry/tests/ — entry validation, lookup, search, categories, content integrity, fetch-metrics
  • packages/cli/tests/ — app-selection, bin flags, config-file I/O, credentials, detect, errors, format, lock file, preferences, registry-cache, registry-config, utils
  • packages/cli/tests/commands/ — add, check, doctor, find, import, list, registry, remove, sync, update command tests

Publishing

Auto-release via conventional commits (.github/workflows/publish.yml). Uses OIDC trusted publishing — no tokens.

• NEVER add NODE_AUTH_TOKEN or NPM_TOKEN environment variables to the publish workflow
• NEVER create or store npm access tokens in repository secrets for publishing

See publishing.md for trigger paths, workflow steps, OIDC rules, and edge cases.

Commit Convention

Follows Conventional Commits v1.0.0. Scopes: core, generators, registry, cli, web. Breaking changes use ! or BREAKING CHANGE: footer.

See commit-convention.md for full types table and examples.

Installed Skills

Skills are installed under .agents/skills/. See the skill files for triggers and descriptions.

References

• SPECIFICATION.md — Complete project specification: schemas, transformation rules per app, registry format, CLI behavior, research appendix
• ROADMAP.md — Planned improvements and open tasks
• design-system.md — Web package design system: colors, fonts, typography, components, layout patterns, and OG image specs
• competence.md — Competence analysis
• css-scroll-spy.md — CSS scroll spy pattern: inline <style> technique required by Turbopack constraint
• file-map.md — Complete file-by-file reference for all 5 packages
• publishing.md — Auto-release workflow, OIDC trusted publishing, trigger paths, edge cases
• commit-convention.md — Conventional Commits types, scopes, and examples
• external-apis.md — External API endpoints, data fetched, error handling, and official docs links
• Repository: https://github.com/RodrigoTomeES/getmcp