# Package Map — Key Files

## `@getmcp/core` (`packages/core/src/`)

| File         | Purpose                                                                                                                                                                                                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schemas.ts` | All Zod schemas: `StdioServerConfig`, `RemoteServerConfig`, `ServerConfig`, `CanonicalMCPConfig`, `RegistryEntry`, `AppId`, `ManifestServerEntry`, `ProjectManifest`, `RegistryAuthMethod`, `RegistrySource`, `RegistryCredential`. Shared `ArgumentVariableSchema` and `ArgumentSchema` extracted from duplicated `packageArguments`/`runtimeArguments` definitions |
| `types.ts`   | TypeScript types inferred from Zod; `ConfigGenerator` and `AppMetadata` interfaces (`configPaths: string \| null` for project-scoped, `globalConfigPaths: PlatformPaths \| null` for global-scoped, `requiresRestart?: boolean`); exported `PlatformPaths` type and `supportsBothScopes()`, `getDefaultScope()` utility functions                                    |
| `utils.ts`   | Type guards (`isStdioConfig`, `isRemoteConfig`) and `inferTransport()`                                                                                                                                                                                                                                                                                               |

## `@getmcp/generators` (`packages/generators/src/`)

| File                | Purpose                                                                                                                                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base.ts`           | `BaseGenerator` abstract class with `generate()`, `generateAll()`, `serialize()`, `detectInstalled()`, `deepMerge()` (with prototype pollution guard), field extraction helpers, shared path constants (`home`, `configHome`, `appData`, `localAppData`, `claudeHome`, `codexHome`) |
| `claude-desktop.ts` | Passthrough — canonical IS the native format                                                                                                                                                                                                                                        |
| `claude-code.ts`    | Near-passthrough; renames `transport` to `type` for remote                                                                                                                                                                                                                          |
| `vscode.ts`         | Root key `servers`; adds `type` field on every server; maps `streamable-http` to `http`                                                                                                                                                                                             |
| `cursor.ts`         | Passthrough (same as Claude Desktop)                                                                                                                                                                                                                                                |
| `cline.ts`          | Adds `alwaysAllow: []` and `disabled: false`                                                                                                                                                                                                                                        |
| `roo-code.ts`       | Adds `alwaysAllow: []`, `disabled: false`; maps `http` to `streamable-http`                                                                                                                                                                                                         |
| `goose.ts`          | YAML output; root key `extensions`; renames `command` to `cmd`, `env` to `envs`; timeout ms to seconds                                                                                                                                                                              |
| `windsurf.ts`       | Remote uses `serverUrl` instead of `url`                                                                                                                                                                                                                                            |
| `opencode.ts`       | Root key `mcp`; merges `command`+`args` into array; renames `env` to `environment`                                                                                                                                                                                                  |
| `zed.ts`            | Root key `context_servers`                                                                                                                                                                                                                                                          |
| `pycharm.ts`        | Passthrough; project-level config at `.ai/mcp/mcp.json` (requires JetBrains AI Assistant plugin)                                                                                                                                                                                    |
| `codex.ts`          | TOML output; root key `mcp_servers`; renames `headers` to `http_headers`; timeout ms to seconds (`startup_timeout_sec`)                                                                                                                                                             |
| `gemini-cli.ts`     | Passthrough; Google Gemini CLI (`mcpServers` root key, JSON); global config at `~/.gemini/settings.json`                                                                                                                                                                            |
| `continue.ts`       | Passthrough; Continue AI code assistant (`mcpServers` root key, JSON); global config at `~/.continue/config.json`                                                                                                                                                                   |
| `amazon-q.ts`       | Passthrough; Amazon Q Developer (`mcpServers` root key, JSON); global config at `~/.aws/amazonq/mcp.json`                                                                                                                                                                           |
| `trae.ts`           | Passthrough; ByteDance Trae IDE (`mcpServers` root key, JSON); project config at `.trae/mcp.json`                                                                                                                                                                                   |
| `bolt-ai.ts`        | Passthrough; BoltAI macOS client (`mcpServers` root key, JSON); macOS-only at `~/Library/Application Support/BoltAI/mcp_config.json`                                                                                                                                                |
| `libre-chat.ts`     | YAML output; LibreChat platform (`mcpServers` root key); custom `serialize()` for YAML; project config at `librechat.yaml`                                                                                                                                                          |
| `antigravity.ts`    | Passthrough; Google Antigravity IDE (`mcpServers` root key, JSON)                                                                                                                                                                                                                   |
| `index.ts`          | Generator registry: maps `AppId` to generator instances; exports `generateConfig()`, `getGenerator()`, `getAppIds()`                                                                                                                                                                |

## `@getmcp/registry` (`packages/registry/`)

| File                         | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------- |   |
| `data/official-servers.json` | Manually curated list of official (first-party) MCP server `officialName` values (reverse-DNS)                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `src/index.ts`               | Registry engine: loads `data/servers.json`, validates via Zod, exposes `getServer()` (ID-only), `getServerBySlug()`, `getServerOrThrow()`, `getAllServers()`, `getOfficialServers()`, `searchServers()`, `getServersByCategory()`, `getCategories()`, `findServerByCommand()`, `resetRegistry()`, `loadFromPath()`, `loadFromEntries()`, `getServersByRegistry()`, `searchServersInRegistry()`, `getAllMetrics()`, `getServerMetrics()`, `getRawServerData()`, `getServersSortedBy()`. Caches sorted arrays for performance. Re-exports `generateSlug` from `id-mapping.ts` |
| `src/enrich.ts`              | GitHub enrichment: maps GitHub topics to getmcp categories, infers runtime from registry type/language, fetches GitHub repo info, builds enrichment metadata                                                                                                                                                                                                                                                                                                                                                                                                                |
| `src/enrichment-types.ts`    | Zod schemas for enrichment (`GetMCPEnrichment` with `isOfficial` flag) and metrics (`GetMCPMetrics` with GitHub/npm/PyPI/Docker sub-schemas); category and runtime enums                                                                                                                                                                                                                                                                                                                                                                                                    |
| `src/extract-config.ts`      | Extracts canonical `ServerConfig` from official MCP registry format; transforms `packages[]`/`remotes[]` into `StdioServerConfig` or `RemoteServerConfig`                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `src/fetch-metrics.ts`       | Metrics fetchers for the sync pipeline: GitHub stars/forks, npm weekly downloads, PyPI monthly downloads, Docker Hub/GHCR pulls; includes retry logic and concurrency control                                                                                                                                                                                                                                                                                                                                                                                               |
| `src/id-mapping.ts`          | Slug generation from official reverse-DNS names (e.g. `io.github.owner/name-mcp` → `name`); `generateSlug()` exported publicly, `generateSlugs()` and `resolveCollisions()` kept for sync pipeline only                                                                                                                                                                                                                                                                                                                                                                     |
| `src/official-api-types.ts`  | Zod schemas matching the official MCP registry API format: `OfficialServer`, `OfficialPackage`, `OfficialRemote`, response wrappers                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `src/transform.ts`           | Transforms official MCP registry entries into `InternalRegistryEntry` format: `id` = official reverse-DNS name (`server.name`), `slug` = URL-friendly derived name, plus `isOfficial` flag and optional `registrySource`. Used by the registry engine, CLI, and web                                                                                                                                                                                                                                                                                                         |
| `scripts/sync.ts`            | Sync pipeline: fetches from official MCP registry API with `version=latest` and `updated_since` for incremental sync, enriches with GitHub data, fetches metrics, stamps official status from curated list, writes `data/servers.json`. Supports `--full` flag to force complete re-sync                                                                                                                                                                                                                                                                                    |

## `@getmcp/cli` (`packages/cli/src/`)

| File                      | Purpose                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bin.ts`                  | Entry point; parses argv, dispatches to commands via `resolveAlias()` with dynamic imports                                                                                                                                                                                                                                                                                                             |
| `detect.ts`               | `resolvePath()`, `getConfigPath()` (accepts optional `requestedScope`), `detectApps()` (delegates to `generator.detectInstalled()`), `detectInstalledApps()`, `resolveAppForScope()`. `DetectedApp` includes `supportsBothScopes` and optional `globalConfigPath` fields                                                                                                                               |
| `format.ts`               | `detectConfigFormat()` — infers config file format (json/jsonc/yaml/toml) from file extension                                                                                                                                                                                                                                                                                                          |
| `config-file.ts`          | Multi-format config file I/O: `readConfigFile()`, `writeConfigFile()`, `mergeServerIntoConfig()`, `removeServerFromConfig()`, `listServersInConfig()` (accepts path or pre-parsed config), `stripJsoncComments()`. Auto-detects format (JSON, JSONC, YAML, TOML) from file extension.                                                                                                                  |
| `lock.ts`                 | Installation tracking via `./getmcp-lock.json` (v2: keys are official reverse-DNS names): `readLockFile()` (auto-migrates v1 slug-keyed → v2), `writeLockFile()`, `trackInstallation()` (accepts optional per-app `scopes` map and `registry`), `trackRemoval()`, `getTrackedServers()`. `LockInstallation` has optional `scopes` and `registry` fields                                                |
| `errors.ts`               | Error types (`CliError`, `ConfigParseError`, `AppNotDetectedError`, `InvalidAppError`, `ServerNotFoundError`, `NonInteractiveError`, `RegistryNotFoundError`, `RegistryAuthError`, `RegistryReservedNameError`) and `formatError()` utility                                                                                                                                                            |
| `utils.ts`                | `parseFlags()` for CLI flag parsing (supports `--global`/`-g`, `--project`, `--registry`, `--name`, `--type`, `--method`, `--insecure` flags), `resolveAlias()` for command alias resolution, `shortenPath()`, `exitIfCancelled()`, `isPromptCancellation()`, unknown flag warnings with Levenshtein-based "did you mean?" suggestions                                                                 |
| `preferences.ts`          | Global user preferences at `~/.config/getmcp/preferences.json` (remembers selected apps across invocations)                                                                                                                                                                                                                                                                                            |
| `registry-cache.ts`       | Multi-registry cache orchestration + re-exports from `registry-cache-io.ts` and `registry-cache-fetch.ts`. Exports `initRegistryCache()`, `refreshRegistryCache(mode?)` (incremental or full), `clearRegistryCache()`, `initProjectRegistries()`, `cleanOrphanedCaches()`                                                                                                                              |
| `registry-cache-io.ts`    | Cache file I/O: paths (`getRegistryCacheDir()`, `getRegistryCacheSubdir()` with path traversal validation), cache metadata read/write, atomic JSON writes, cached server reading                                                                                                                                                                                                                       |
| `registry-cache-fetch.ts` | Paginated API fetching (`fetchRegistryServers()`) with `MAX_PAGES=1000` limit, entry merging (`mergeEntries()`), auth header integration                                                                                                                                                                                                                                                               |
| `registry-config.ts`      | Registry configuration CRUD: `addRegistry()`, `removeRegistry()`, `getAllRegistries()`, `getEffectiveRegistries()`. Official registry always injected at runtime. Storage at `~/.config/getmcp/registries.json`                                                                                                                                                                                        |
| `credentials.ts`          | Credential management: `storeCredential()`, `removeCredential()`, `resolveCredential()`, `buildAuthHeaders()`, `getEnvVarName()`, `isValidHeaderName()`. Env var override (`GETMCP_REGISTRY_<NAME>_TOKEN`). Storage at `~/.config/getmcp/credentials.json` (0600 permissions). Header name validation blocks unsafe headers (`host`, `content-length`, `transfer-encoding`, `cookie`, `authorization`) |
| `commands/add.ts`         | Interactive add workflow: pick server, prompt env vars, detect apps, generate + merge configs. Supports `--registry` flag for targeting specific registry                                                                                                                                                                                                                                              |
| `commands/remove.ts`      | Interactive remove workflow with server picker when no args, `--dry-run` and `--yes` support                                                                                                                                                                                                                                                                                                           |
| `commands/list.ts`        | List/search/filter servers                                                                                                                                                                                                                                                                                                                                                                             |
| `commands/find.ts`        | Interactive fuzzy server search with inline add flow (aliases: `search`, `s`, `f`)                                                                                                                                                                                                                                                                                                                     |
| `commands/check.ts`       | Validate tracked installations against registry and app configs                                                                                                                                                                                                                                                                                                                                        |
| `commands/update.ts`      | Re-generate and merge configs for all tracked installations                                                                                                                                                                                                                                                                                                                                            |
| `commands/doctor.ts`      | Health diagnostics: installed apps, config parsing, registry status, orphaned servers, env vars, runtime dependencies, registry health (ping + auth check)                                                                                                                                                                                                                                             |
| `commands/import.ts`      | Scan app configs for existing servers and adopt them into getmcp tracking                                                                                                                                                                                                                                                                                                                              |
| `commands/sync.ts`        | Read `getmcp.json` manifest and install all declared servers into detected apps. Supports manifest `registries` for project-level registry sources                                                                                                                                                                                                                                                     |
| `commands/registry.ts`    | Registry management: `add`, `remove`, `list`, `login`, `logout` subcommands. Derives name from URL hostname, pings registry, tests credentials. Exports `registryCommand()` and `deriveRegistryName()`                                                                                                                                                                                                 |

## `@getmcp/web` (`packages/web/src/`)

| File                                   | Purpose                                                                                                                                        |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `app/layout.tsx`                       | Root layout with Vercel Analytics and Speed Insights                                                                                           |
| `app/not-found.tsx`                    | Custom 404 page with ASCII art and terminal simulation                                                                                         |
| `app/page.tsx`                         | Homepage with hero section and search                                                                                                          |
| `app/docs/page.tsx`                    | Documentation page with getting started, supported apps, library usage, and more                                                               |
| `app/docs/loading.tsx`                 | Loading skeleton for the docs page                                                                                                             |
| `app/servers/page.tsx`                 | Server directory index page with search and filters                                                                                            |
| `app/servers/[id]/page.tsx`            | Dynamic server detail page with two-column layout (main + sidebar), hero with inline stats, rich metrics display                               |
| `app/servers/loading.tsx`              | Loading skeleton for the servers directory page                                                                                                |
| `app/category/[slug]/page.tsx`         | 14 category landing pages with per-category server grids                                                                                       |
| `app/guides/page.tsx`                  | Guides index page listing all 19 app-specific MCP setup guides                                                                                 |
| `app/guides/[app]/page.tsx`            | 19 app-specific MCP setup guides                                                                                                               |
| `app/guides/loading.tsx`               | Loading skeleton for the guides pages                                                                                                          |
| `lib/guide-data.ts`                    | Guide content data module (names, overviews, config details, troubleshooting)                                                                  |
| `lib/format.ts`                        | Shared formatting utilities: `compactNumber()`, `relativeTime()`                                                                               |
| `components/AnimatedCommand.tsx`       | Client component: typewriter-style CLI command animation cycling through getmcp commands with copy-to-clipboard support                        |
| `components/AsciiArt.tsx`              | Animated ASCII art hero with character-by-character reveal, uses Fira Mono font                                                                |
| `components/CategoryGrid.tsx`          | Grid of category cards with server counts linking to category pages                                                                            |
| `components/CodeBlock.tsx`             | Client component: syntax-highlighted code block with copy button                                                                               |
| `components/ConfigViewer.tsx`          | Client component: tab selector for all 19 apps with mobile dropdown, shows generated config snippet with copy button, localStorage persistence |
| `components/DocsSidebar.tsx`           | Sticky docs table-of-contents sidebar with CSS scroll-spy highlighting                                                                         |
| `components/FormatShowcase.tsx`        | Grid showcasing config format differences across apps (JSON, YAML, TOML)                                                                       |
| `components/MetaItem.tsx`              | Label-value metadata display pair with optional monospace styling                                                                              |
| `components/PackageManagerCommand.tsx` | Client component: package manager command with npm/npx/bunx/pnpx tabs and copy button, persisted selection via localStorage                    |
| `components/Pagination.tsx`            | Paginated navigation with page numbers, ellipsis, and prev/next buttons                                                                        |
| `components/Pill.tsx`                  | Shared pill/tab button with `aria-pressed` support                                                                                             |
| `components/PopularServers.tsx`        | Curated grid of 12 popular server cards for the homepage                                                                                       |
| `components/SearchBar.tsx`             | Search, category, runtime, transport, and official filter component                                                                            |
| `components/ServerCard.tsx`            | Server listing card with runtime badge, official badge, and author display                                                                     |
| `components/ServerSidebar.tsx`         | Server detail sidebar: stats grid (stars/forks/downloads/issues), details, links, tags                                                         |
| `components/StatBadge.tsx`             | Inline stat pill with icon + value + optional label suffix                                                                                     |
| `components/SupportedApps.tsx`         | Grid of all 19 supported apps with format badges linking to setup guides                                                                       |
| _(icons)_                              | No wrapper file — icons imported directly from `lucide-react` and `@icons-pack/react-simple-icons` at each usage site                          |
