{
  "markdown": "# MCP Architector\n\n[![npm version](https://img.shields.io/npm/v/mcp-architector.svg)](https://www.npmjs.com/package/mcp-architector)\n[![GitHub](https://img.shields.io/github/license/theSharque/mcp-architect)](https://github.com/theSharque/mcp-architect)\n\n> Model Context Protocol (MCP) server for architecture and system design\n\n**Local-first MCP server** that stores and manages project architecture information. All data is stored locally in `~/.mcp-architector` for maximum privacy and confidentiality.\n\n📦 **Install**: `npm install -g mcp-architector` or use via npx\n🌐 **npm**: https://www.npmjs.com/package/mcp-architector\n🔗 **GitHub**: https://github.com/theSharque/mcp-architect\n\n## How to connect to Claude Desktop / IDE\n\nAdd the server to your MCP config. Example for **claude_desktop_config.json**:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n**Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-architector\"],\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\nFor **Cursor IDE**: Settings → Features → Model Context Protocol → Edit Config, then add the same block inside `mcpServers`. See the [Integration](#integration) section for more options.\n\n## Cursor rule (recommended)\n\nFor **Cursor IDE** and **Cursor Cloud Agents**, use a phased onboarding rule so the agent does not dump the whole repo into context in one shot.\n\n1. Copy [`.cursor/rules/architector-onboarding.mdc`](.cursor/rules/architector-onboarding.mdc) into **your project** (the repo you are documenting):\n\n   ```bash\n   mkdir -p /path/to/your-app/.cursor/rules\n   cp /path/to/mcp-architector/.cursor/rules/architector-onboarding.mdc /path/to/your-app/.cursor/rules/\n   ```\n\n2. Ensure MCP Architector is connected. The agent must call `list-projects` and pass `projectId` on every write — do not rely on omitting it.\n\n3. Ask in chat, for example: *\"Onboard this repo into architector — phase 0 plan first\"* or *\"Import architecture module by module\"*.\n\nThe rule is **`alwaysApply: false`** — Cursor attaches it when the task matches architecture import/onboarding. It enforces: structure → one module per step → `validate` after each step → compact tools only.\n\nIf you develop **this** server repo, keep the same file here so contributors and Cloud Agents follow the same workflow when updating `~/.mcp-architector/_qs_mcp-architector/`.\n\n## Overview\n\nStore and manage project architecture, modules, scripts, data flow, and usage examples - all locally with complete privacy.\n\n## Features\n\n- **Local Storage**: All data stored in `~/.mcp-architector` (privacy-first)\n- **Project Architecture**: Store and retrieve overall project architecture\n- **Module Details**: Detailed information about each module\n- **Resources**: Access architecture data via resources\n\n## Storage Structure\n\n```\n~/.mcp-architector/\n└── {projectId}/\n    ├── architecture.json      # Modules + dataFlow (vertical structure)\n    ├── modules/\n    │   ├── {moduleId}.json\n    │   └── ...\n    ├── entries/\n    │   ├── index.json         # Catalog (no duplicate bodies)\n    │   └── {entryId}.json     # Canonical facts (API, domain, flows, …)\n    ├── slices/\n    │   └── {sliceId}.json     # Custom filters only (no items)\n```\n\n## Data model\n\n| Layer | Purpose | Tools |\n|-------|---------|-------|\n| **Modules** | Vertical structure: components, dependencies, dataFlow | `set-project-architecture`, `set-module-details`, `set-module-data-flow`, `rebuild-data-flow`, `validate-architecture` |\n| **Entries** | Single source of truth for horizontal facts (one fact = one file) | `set-entry`, `set-entries`, `get-entry`, `list-entries` |\n| **Slices** | Read-only views over entries (built-in or custom filters) | `list-slices`, `get-slice` |\n\n**Anti-patterns (no duplication):** Do not copy `module.description` into `entry.summary`. Link with `refs.moduleName`. Slices never store item copies—only filters in `slices/*.json`.\n\n**Do not edit `~/.mcp-architector` directly** — always use MCP tools so timestamps, merge semantics, and dataFlow inverse sync stay consistent.\n\n## Agent workflow\n\n1. `list-projects` — find `projectId` for this workspace (query by folder name). Pass it to every other tool. Never omit. Never use `default-project`.\n2. **Structure task** → `get-project-architecture` / `set-project-architecture`.\n3. **Each module** → `set-module-details` with `files` + **`facts[]`** (endpoints, entities, glossary) in the same call, or `set-entries` / `set-entry` with `refs.moduleName`.\n4. **Single module graph edge** → `set-module-data-flow`.\n5. **Bulk rebuild flow (many modules)** → `rebuild-data-flow`.\n6. **After edits, verify everything** → `validate` (summary + `issues[]`; no full project load).\n7. **Need a category** (all APIs, all domain terms) → `list-slices` → `get-slice` with `format=compact` or `table`; use `offset` when `hasMore` is true.\n8. **Find by name** → `search-entries` → `get-entry` for full payload.\n9. **After code refactor (same modules)** → `refactor-architecture`: `scan` → dryRun preview → apply with `confirm=true`.\n\n| Scenario | Tool |\n|----------|------|\n| Update one module + its APIs/facts | `set-module-details` with `facts[]` |\n| Bulk facts for a domain | `set-entries` with `moduleName` |\n| Patch dataFlow for one module | `set-module-data-flow` |\n| Rebuild all module edges | `rebuild-data-flow` |\n| Diagnose graph + empty slices | `validate` (or `validate-architecture`) |\n| Catalog JSON corrupt (extra data after JSON) | `fix-data` |\n| Sync paths/names after refactor | `refactor-architecture` (dryRun, then confirm) |\n| Index out of sync | `rebuild-entry-index` |\n| Create project from scratch | `set-project-architecture` with `replaceModules: true` |\n| Onboard a fresh git clone (phased) | Copy [`.cursor/rules/architector-onboarding.mdc`](.cursor/rules/architector-onboarding.mdc) → ask agent to onboard phase by phase |\n\n**Full project picture:** modules alone do not populate slices — without `http-endpoint` (and other kinds) entries, slice `api` stays empty. New module → add `facts` or entries in the same step.\n\nExample: `set-module-details` with `facts: [{ kind: \"http-endpoint\", title: \"POST /orders\", ... }]`, then `get-slice` `sliceId=api` `format=table`.\n\n## Quick Start\n\n### For Users (using npm package)\n\n```bash\n# No installation needed - use directly in Cursor/Claude Desktop\n# Just configure it as described in Integration section below\n```\n\n### For Developers\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/theSharque/mcp-architect.git\ncd mcp-architect\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the project:\n```bash\nnpm run build\n```\n\n## Usage\n\n### Development Mode\n\nRun with hot reload:\n```bash\nnpm run dev\n```\n\n### Production Mode\n\nStart the server:\n```bash\nnpm start\n```\n\n### MCP Inspector\n\nDebug and test your server with the MCP Inspector:\n```bash\nnpm run inspector\n```\n\n## Integration\n\n### Cursor IDE\n\n1. Open Cursor Settings → Features → Model Context Protocol\n2. Click \"Edit Config\" button\n3. Add one of the configurations below\n\n#### Option 1: Via npm (Recommended)\n\nInstalls from npm registry automatically:\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-architector\"],\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n#### Option 2: Via npm link (Development)\n\nFor local development with live changes:\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"mcp-architector\",\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\nRequires: `cd /path/to/mcp-architector && npm link -g`\n\n#### Option 3: Direct path\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-architector/dist/index.js\"],\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-architector\"],\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n### Continue.dev\n\nEdit `.continue/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"architector\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-architector\"],\n      \"env\": {\n        \"MCP_PROJECT_ID\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n### Using Project ID\n\n`projectId` is **required** on every tool except `list-projects`. There is no default dump project.\n\n1. **Call `list-projects` first** (optionally with `query` = workspace folder name)\n2. **Pass the matching `projectId`** to every other tool\n3. If none matches, create one with `set-project-architecture` using a stable id from the workspace path (e.g. `_qs_my-app`)\n\n`MCP_PROJECT_ID` is only a hint (`isCurrent` / `suggestedProjectId`). It is **not** used as a silent write target. `default-project` and unsubstituted `${workspaceFolder}` ids are forbidden.\n\n## Tools\n\n### set-project-architecture\n\nCreates or updates the overall architecture for a project. **By default merges** modules and dataFlow by name; omit `dataFlow` to preserve existing flow. `dependsOn` is canonical; `providesTo` is recomputed on save.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`. Never omit. `default-project` is forbidden.\n- `description`: Overall project description\n- `modules`: Array of module objects with:\n  - `name`: Module name\n  - `description`: Brief description of the module\n  - `inputs` (optional): What this module requires to work\n  - `outputs` (optional): What this module produces or generates\n- `dataFlow` (optional): Object describing data flow between modules (omit to keep existing):\n  - Key: module name\n  - Value: object with:\n    - `dependsOn` (optional): Array of module names this module depends on\n    - `providesTo` (optional): Derived on save from all `dependsOn` edges\n    - `dataTransformation` (optional): How data is transformed between modules\n- `replaceModules` (optional): Replace entire modules list (default `false` = merge by name)\n- `replaceDataFlow` (optional): Replace entire dataFlow (default `false` = merge by module name)\n\n**Output:**\n- Project ID and success message\n\n### get-project-architecture\n\nRetrieves the overall architecture of the project.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`. Never omit. `default-project` is forbidden.\n\n**Output:**\n- Complete project architecture\n\n### list-projects\n\nLists all projects in local storage (`~/.mcp-architector`). **Call this first.** Match the current workspace by folder name, then pass `projectId` to every other tool.\n\n**Input:**\n- `query` (optional): Filter by substring in projectId or description (case-insensitive)\n\n**Output:**\n- `projects[]`: `projectId`, `description`, `moduleCount`, `updatedAt`, `isCurrent` (hint from `MCP_PROJECT_ID`), `forbidden` (`default-project` and unsubstituted workspaceFolder dumps)\n- `suggestedProjectId`: current `MCP_PROJECT_ID` when it is a valid id, else `null`\n- `reminder`: always pass `projectId`; never use `default-project`\n\n### Entries and slices\n\n| Tool | Purpose |\n|------|---------|\n| `set-entry` | Upsert one fact; response may include `reminder` if modules missing or unlinked |\n| `set-entries` | Bulk upsert (max 200); optional `moduleName` sets `refs.moduleName` on all |\n| `get-entry` | Full entry by `id` |\n| `delete-entry` | Remove entry |\n| `list-entries` | Catalog without payload; filter by `kind`, `tags`, `query` |\n| `search-entries` | Compact text search with `snippet`, `slices`, `moduleName`, pagination; filters: `moduleName`, `kind`, `tags` |\n| `list-slices` | Built-in + custom slices with entry counts |\n| `get-slice` | Filtered view: `sliceId`, `format`, `query`, `limit`, `offset`, `hasMore` |\n| `set-slice` | Save custom filter (`kinds`, `tags`) — no items |\n| `delete-slice` | Remove custom slice |\n| `rebuild-entry-index` | Rebuild `entries/index.json` from entry files |\n| `fix-data` | Repair leftover/corrupt catalog JSON; rebuild index |\n\n**Built-in `sliceId` values:** `api`, `persistence`, `events`, `domain`, `flows`, `integrations`, `config`, `runtime`, `decisions`, `scripts`.\n\n### search-entries\n\nCompact navigation search—returns enough context to pick a hit, then call `get-entry` for full payload.\n\n**Input:** `query` (required), `moduleName`, `kind`, `tags`, `limit` (default 10, max 50), `offset` (default 0)\n\n**Output:** `summary`, `total`, `returned`, `offset`, `hasMore`, `results[]` with `snippet`, `matchedIn`, `slices`, `moduleName` plus legacy `summary`, `tags`, `refs`\n\n**Recommended `kind` examples (any string allowed):**\n\n| sliceId | kinds |\n|---------|-------|\n| api | `http-endpoint`, `grpc-method`, `mcp-tool`, `cli-command`, … |\n| persistence | `db-table`, `entity`, `repository` |\n| domain | `glossary`, `invariant`, `lifecycle` |\n| scripts | `script` — use `set-entry` / `get-slice sliceId=scripts` |\n\n### set-module-details\n\nCreates or updates detailed information about a module. **Slices read entries, not module text** — pass `facts[]` to create linked entries in one call.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n- `name`: Module name\n- `description`: Detailed description of the module\n- `inputs`: What the module accepts as input\n- `outputs`: What the module produces as output\n- `dependencies` (optional): List of module dependencies (syncs to `dataFlow.dependsOn` when provided)\n- `files` (optional): List of files belonging to this module\n- `facts` (optional): Array of horizontal facts (`kind`, `title`, `summary`, …) — each upserted as entry with `refs.moduleName` = module name\n- `usageExamples` (optional): Array of usage examples with fields:\n  - `title`: Example title\n  - `description` (optional): Description of the example\n  - `command` (optional): Command or code snippet\n  - `input` (optional): Input data\n  - `output` (optional): Expected output\n  - `notes` (optional): Additional notes about the example\n- `notes` (optional): Additional notes\n\n**Output:**\n- Module ID and success message\n\n### set-module-data-flow\n\nPatches `dataFlow` for a single module without sending the full architecture.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n- `moduleName`: Module name\n- `dependsOn` (optional): Modules this module depends on (canonical)\n- `dataTransformation` (optional): How data is transformed\n- `syncInverse` (optional): Recompute `providesTo` (default `true`)\n\n**Output:**\n- Module name and success message\n\n### rebuild-data-flow\n\nRebuilds `dataFlow` for all modules from module file `dependencies` or existing `dependsOn` edges. Replaces bulk manual edits to `architecture.json`.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n- `source` (optional): `module-dependencies` (default) or `dataFlow-dependsOn`\n- `syncInverse` (optional): Recompute `providesTo` (default `true`)\n- `pruneOrphans` (optional): Remove invalid module references (default `true`)\n\n**Output:**\n- `edgesAdded`, `edgesRemoved`, `modulesUpdated`, message\n\n### validate\n\n**Primary post-edit check.** Read-only validation with a compact agent-friendly report. Does not modify data.\n\n**Checks (only rules we can verify from stored JSON):**\n- dataFlow: inverse drift, dangling `dependsOn`/`providesTo`, orphan flow keys\n- `module.dependencies` vs `dataFlow.dependsOn`\n- entries: `entries-without-modules`, `entry-unlinked`, `orphan-entry-module`, `module-no-entries`, `module-missing-api` / `module-missing-persistence`, `entry-slice-orphan`, `module-too-many-entries`, `module-too-few-entries`\n- storage: missing `modules/{id}.json`, orphan module files, entry index drift\n- slices: empty built-in `api` / `domain` / `persistence` when modules exist\n\n**Input:** `projectId`, `checkInverse`, `checkModuleDeps`, `checkEntryCoverage`, `checkStorage`, `checkEmptySlices`, `checkSliceCoverage`, `checkModuleEntryCounts`, `moduleEntryMax` (default `50`), `moduleEntryMin` (optional; omit to disable min check) — all boolean flags default `true` unless noted\n\n**Output:** `valid`, `issueCount`, `summary`, `stats`, `issuesByKind`, `issues[]`, `coverage`, `checksRun`\n\n### fix-data\n\nRun when catalog JSON is corrupt (for example `list-modules` / `validate` fail with extra data after JSON). Trims leftover bytes after the first valid JSON object in `architecture.json`, `modules/`, `entries/`, and `slices/`; removes leftover `.tmp` files; rebuilds the entry index. Does not delete facts. Catalog writes use temp+rename so this leftover cannot recur.\n\n**Input:** `projectId`, `dryRun` (optional, default `false`)\n\n**Output:** `summary`, `scanned`, `repaired`, `unreadable`, `tmpRemoved`, `indexItemCount`, `files[]` (repaired/unreadable only)\n\n### refactor-architecture\n\nPreview or apply in-architector sync after a code refactor when module boundaries stay the same. Agent is the source of truth — no workspace or git access. Default `dryRun=true`.\n\n**Workflow:** (1) `scan` with `file` or `text` → compact hits, (2) build mutation ops, (3) dryRun preview, (4) apply with `dryRun=false` and `confirm=true`.\n\n**Operations (max 10 per call):** `scan`, `move-file`, `replace-path-prefix`, `rename-text`, `patch-entry`, `merge-files`, `remove-file-ref`.\n\n**Scope (optional):** `moduleName`, `kinds`, `tags` — limits which entries/modules are touched.\n\nOrphan entries with empty `refs.files` and no `refs.entryIds` are deleted after file operations.\n\n**Input:** `projectId`, `operations[]`, `scope`, `dryRun` (default `true`), `confirm` (required when applying), `limit`, `offset`\n\n**Output:** `summary`, `stats`, `hits` (scan) or paginated `changes`, `warnings`, `hasMore`\n\n### validate-architecture\n\nSame as `validate` (legacy alias). Prefer `validate` after edits.\n\n**Output:**\n- `valid` (boolean), `issues` array\n\n### get-module-details\n\nRetrieves detailed information about a specific module.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n- `moduleName`: Name of the module to retrieve\n\n**Output:**\n- Complete module details\n\n### list-modules\n\nLists all modules in the project architecture.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n\n**Output:**\n- Array of module summaries\n\n### delete-module\n\nDeletes a module from the project architecture.\n\n**Input:**\n- `projectId` (required): Project ID from `list-projects`\n- `moduleName`: Name of the module to delete\n\n**Output:**\n- Success message\n\n## Resources\n\n### architecture\n\nProvides access to project architecture as a resource.\n\n**Usage:**\nAccess via URI: `arch://{projectId}`\n\n### module\n\nProvides access to module details as a resource.\n\n**Usage:**\nAccess via URI: `module://{projectId}/{moduleId}`\n\n## Development\n\n### Project Structure\n\n```\nmcp-architector/\n├── src/\n│   ├── index.ts          # Main server implementation\n│   ├── types.ts          # Type definitions\n│   └── storage.ts        # Storage utilities\n├── dist/                 # Compiled output (generated)\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Project ID\n\nThe server stores each project in `~/.mcp-architector/{projectId}/`. `projectId` must be passed explicitly on every tool except `list-projects`.\n\n- Call `list-projects` (with `query` = workspace folder name) to find the id\n- `MCP_PROJECT_ID` is only a listing hint (`isCurrent` / `suggestedProjectId`), not a silent write target\n- `default-project` and unsubstituted `${workspaceFolder}` ids are forbidden\n\nTo start a new project, pass a stable id derived from the workspace path (e.g. `_qs_my-app`) to `set-project-architecture`.\n\n### Extending the Server\n\nTo add new tools, resources, or prompts, edit `src/index.ts`:\n\n```typescript\n// Add a tool\nserver.registerTool(\n  \"tool-name\",\n  { /* tool config */ },\n  async (params) => { /* handler */ }\n);\n\n// Add a resource\nserver.registerResource(\n  \"resource-name\",\n  new ResourceTemplate(\"uri-template\", { /* options */ }),\n  { /* resource config */ },\n  async (uri, params) => { /* handler */ }\n);\n\n// Add a prompt\nserver.registerPrompt(\n  \"prompt-name\",\n  { /* prompt config */ },\n  (args) => { /* handler */ }\n);\n```\n\n## License\n\nMIT\n\n",
  "bytes": 20438,
  "sha": "b4d55e79ff4f9479040295864600f0b55e0dfa43387c8af64a855a0376aee198",
  "repo_slug": "thesharque/mcp-architect",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thesharque_mcp_architector_4a09d07e/readme"
}