mcp-architector

MCP Architector

Model Context Protocol (MCP) server for architecture and system design

Local-first MCP server that stores and manages project architecture information. All data is stored locally in ~/.mcp-architector for maximum privacy and confidentiality.

📦 Install: npm install -g mcp-architector or use via npx 🌐 npm: https://www.npmjs.com/package/mcp-architector 🔗 GitHub: https://github.com/theSharque/mcp-architect

How to connect to Claude Desktop / IDE

Add the server to your MCP config. Example for claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

For Cursor IDE: Settings → Features → Model Context Protocol → Edit Config, then add the same block inside mcpServers. See the Integration section for more options.

Cursor rule (recommended)

For 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.

1. Copy .cursor/rules/architector-onboarding.mdc into your project (the repo you are documenting):

   mkdir -p /path/to/your-app/.cursor/rules
   cp /path/to/mcp-architector/.cursor/rules/architector-onboarding.mdc /path/to/your-app/.cursor/rules/
   

2. Ensure MCP Architector is connected. The agent must call list-projects and pass projectId on every write — do not rely on omitting it.

3. Ask in chat, for example: "Onboard this repo into architector — phase 0 plan first" or "Import architecture module by module".

The 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.

If 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/.

Overview

Store and manage project architecture, modules, scripts, data flow, and usage examples - all locally with complete privacy.

Features

• Local Storage: All data stored in ~/.mcp-architector (privacy-first)
• Project Architecture: Store and retrieve overall project architecture
• Module Details: Detailed information about each module
• Resources: Access architecture data via resources

Storage Structure

~/.mcp-architector/
└── {projectId}/
    ├── architecture.json      # Modules + dataFlow (vertical structure)
    ├── modules/
    │   ├── {moduleId}.json
    │   └── ...
    ├── entries/
    │   ├── index.json         # Catalog (no duplicate bodies)
    │   └── {entryId}.json     # Canonical facts (API, domain, flows, …)
    ├── slices/
    │   └── {sliceId}.json     # Custom filters only (no items)

Data model

Layer	Purpose	Tools
Modules	Vertical structure: components, dependencies, dataFlow	set-project-architecture, set-module-details, set-module-data-flow, rebuild-data-flow, validate-architecture
Entries	Single source of truth for horizontal facts (one fact = one file)	set-entry, set-entries, get-entry, list-entries
Slices	Read-only views over entries (built-in or custom filters)	list-slices, get-slice

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.

Do not edit ~/.mcp-architector directly — always use MCP tools so timestamps, merge semantics, and dataFlow inverse sync stay consistent.

Agent workflow

1. list-projects — find projectId for this workspace (query by folder name). Pass it to every other tool. Never omit. Never use default-project.
2. Structure task → get-project-architecture / set-project-architecture.
3. Each module → set-module-details with files + facts[] (endpoints, entities, glossary) in the same call, or set-entries / set-entry with refs.moduleName.
4. Single module graph edge → set-module-data-flow.
5. Bulk rebuild flow (many modules) → rebuild-data-flow.
6. After edits, verify everything → validate (summary + issues[]; no full project load).
7. Need a category (all APIs, all domain terms) → list-slices → get-slice with format=compact or table; use offset when hasMore is true.
8. Find by name → search-entries → get-entry for full payload.
9. After code refactor (same modules) → refactor-architecture: scan → dryRun preview → apply with confirm=true.

Scenario	Tool
Update one module + its APIs/facts	set-module-details with facts[]
Bulk facts for a domain	set-entries with moduleName
Patch dataFlow for one module	set-module-data-flow
Rebuild all module edges	rebuild-data-flow
Diagnose graph + empty slices	validate (or validate-architecture)
Catalog JSON corrupt (extra data after JSON)	fix-data
Sync paths/names after refactor	refactor-architecture (dryRun, then confirm)
Index out of sync	rebuild-entry-index
Create project from scratch	set-project-architecture with replaceModules: true
Onboard a fresh git clone (phased)	Copy .cursor/rules/architector-onboarding.mdc → ask agent to onboard phase by phase

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.

Example: set-module-details with facts: [{ kind: "http-endpoint", title: "POST /orders", ... }], then get-slice sliceId=api format=table.

Quick Start

For Users (using npm package)

# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below

For Developers

1. Clone the repository:

git clone https://github.com/theSharque/mcp-architect.git
cd mcp-architect

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Development Mode

Run with hot reload:

npm run dev

Production Mode

Start the server:

npm start

MCP Inspector

Debug and test your server with the MCP Inspector:

npm run inspector

Integration

Cursor IDE

1. Open Cursor Settings → Features → Model Context Protocol
2. Click "Edit Config" button
3. Add one of the configurations below

Option 1: Via npm (Recommended)

Installs from npm registry automatically:

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Option 2: Via npm link (Development)

For local development with live changes:

{
  "mcpServers": {
    "architector": {
      "command": "mcp-architector",
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Requires: cd /path/to/mcp-architector && npm link -g

Option 3: Direct path

{
  "mcpServers": {
    "architector": {
      "command": "node",
      "args": ["/path/to/mcp-architector/dist/index.js"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Continue.dev

Edit .continue/config.json:

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Using Project ID

projectId is required on every tool except list-projects. There is no default dump project.

1. Call list-projects first (optionally with query = workspace folder name)
2. Pass the matching projectId to every other tool
3. If none matches, create one with set-project-architecture using a stable id from the workspace path (e.g. _qs_my-app)

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.

Tools

set-project-architecture

Creates 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.

Input:

• projectId (required): Project ID from list-projects. Never omit. default-project is forbidden.
• description: Overall project description
• modules: Array of module objects with:
  • name: Module name
  • description: Brief description of the module
  • inputs (optional): What this module requires to work
  • outputs (optional): What this module produces or generates
• dataFlow (optional): Object describing data flow between modules (omit to keep existing):
  • Key: module name
  • Value: object with:
    • dependsOn (optional): Array of module names this module depends on
    • providesTo (optional): Derived on save from all dependsOn edges
    • dataTransformation (optional): How data is transformed between modules
• replaceModules (optional): Replace entire modules list (default false = merge by name)
• replaceDataFlow (optional): Replace entire dataFlow (default false = merge by module name)

Output:

• Project ID and success message

get-project-architecture

Retrieves the overall architecture of the project.

Input:

• projectId (required): Project ID from list-projects. Never omit. default-project is forbidden.

Output:

• Complete project architecture

list-projects

Lists all projects in local storage (~/.mcp-architector). Call this first. Match the current workspace by folder name, then pass projectId to every other tool.

Input:

• query (optional): Filter by substring in projectId or description (case-insensitive)

Output:

• projects[]: projectId, description, moduleCount, updatedAt, isCurrent (hint from MCP_PROJECT_ID), forbidden (default-project and unsubstituted workspaceFolder dumps)
• suggestedProjectId: current MCP_PROJECT_ID when it is a valid id, else null
• reminder: always pass projectId; never use default-project

Entries and slices

Tool	Purpose
set-entry	Upsert one fact; response may include reminder if modules missing or unlinked
set-entries	Bulk upsert (max 200); optional moduleName sets refs.moduleName on all
get-entry	Full entry by id
delete-entry	Remove entry
list-entries	Catalog without payload; filter by kind, tags, query
search-entries	Compact text search with snippet, slices, moduleName, pagination; filters: moduleName, kind, tags
list-slices	Built-in + custom slices with entry counts
get-slice	Filtered view: sliceId, format, query, limit, offset, hasMore
set-slice	Save custom filter (kinds, tags) — no items
delete-slice	Remove custom slice
rebuild-entry-index	Rebuild entries/index.json from entry files
fix-data	Repair leftover/corrupt catalog JSON; rebuild index

Built-in sliceId values: api, persistence, events, domain, flows, integrations, config, runtime, decisions, scripts.

search-entries

Compact navigation search—returns enough context to pick a hit, then call get-entry for full payload.

Input: query (required), moduleName, kind, tags, limit (default 10, max 50), offset (default 0)

Output: summary, total, returned, offset, hasMore, results[] with snippet, matchedIn, slices, moduleName plus legacy summary, tags, refs

Recommended kind examples (any string allowed):

sliceId	kinds
api	http-endpoint, grpc-method, mcp-tool, cli-command, …
persistence	db-table, entity, repository
domain	glossary, invariant, lifecycle
scripts	script — use set-entry / get-slice sliceId=scripts

set-module-details

Creates or updates detailed information about a module. Slices read entries, not module text — pass facts[] to create linked entries in one call.

Input:

• projectId (required): Project ID from list-projects
• name: Module name
• description: Detailed description of the module
• inputs: What the module accepts as input
• outputs: What the module produces as output
• dependencies (optional): List of module dependencies (syncs to dataFlow.dependsOn when provided)
• files (optional): List of files belonging to this module
• facts (optional): Array of horizontal facts (kind, title, summary, …) — each upserted as entry with refs.moduleName = module name
• usageExamples (optional): Array of usage examples with fields:
  • title: Example title
  • description (optional): Description of the example
  • command (optional): Command or code snippet
  • input (optional): Input data
  • output (optional): Expected output
  • notes (optional): Additional notes about the example
• notes (optional): Additional notes

Output:

• Module ID and success message

set-module-data-flow

Patches dataFlow for a single module without sending the full architecture.

Input:

• projectId (required): Project ID from list-projects
• moduleName: Module name
• dependsOn (optional): Modules this module depends on (canonical)
• dataTransformation (optional): How data is transformed
• syncInverse (optional): Recompute providesTo (default true)

Output:

• Module name and success message

rebuild-data-flow

Rebuilds dataFlow for all modules from module file dependencies or existing dependsOn edges. Replaces bulk manual edits to architecture.json.

Input:

• projectId (required): Project ID from list-projects
• source (optional): module-dependencies (default) or dataFlow-dependsOn
• syncInverse (optional): Recompute providesTo (default true)
• pruneOrphans (optional): Remove invalid module references (default true)

Output:

• edgesAdded, edgesRemoved, modulesUpdated, message

validate

Primary post-edit check. Read-only validation with a compact agent-friendly report. Does not modify data.

Checks (only rules we can verify from stored JSON):

• dataFlow: inverse drift, dangling dependsOn/providesTo, orphan flow keys
• module.dependencies vs dataFlow.dependsOn
• 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
• storage: missing modules/{id}.json, orphan module files, entry index drift
• slices: empty built-in api / domain / persistence when modules exist

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

Output: valid, issueCount, summary, stats, issuesByKind, issues[], coverage, checksRun

fix-data

Run 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.

Input: projectId, dryRun (optional, default false)

Output: summary, scanned, repaired, unreadable, tmpRemoved, indexItemCount, files[] (repaired/unreadable only)

refactor-architecture

Preview 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.

Workflow: (1) scan with file or text → compact hits, (2) build mutation ops, (3) dryRun preview, (4) apply with dryRun=false and confirm=true.

Operations (max 10 per call): scan, move-file, replace-path-prefix, rename-text, patch-entry, merge-files, remove-file-ref.

Scope (optional): moduleName, kinds, tags — limits which entries/modules are touched.

Orphan entries with empty refs.files and no refs.entryIds are deleted after file operations.

Input: projectId, operations[], scope, dryRun (default true), confirm (required when applying), limit, offset

Output: summary, stats, hits (scan) or paginated changes, warnings, hasMore

validate-architecture

Same as validate (legacy alias). Prefer validate after edits.

Output:

• valid (boolean), issues array

get-module-details

Retrieves detailed information about a specific module.

Input:

• projectId (required): Project ID from list-projects
• moduleName: Name of the module to retrieve

Output:

• Complete module details

list-modules

Lists all modules in the project architecture.

Input:

• projectId (required): Project ID from list-projects

Output:

• Array of module summaries

delete-module

Deletes a module from the project architecture.

Input:

• projectId (required): Project ID from list-projects
• moduleName: Name of the module to delete

Output:

• Success message

Resources

architecture

Provides access to project architecture as a resource.

Usage: Access via URI: arch://{projectId}

module

Provides access to module details as a resource.

Usage: Access via URI: module://{projectId}/{moduleId}

Development

Project Structure

mcp-architector/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── types.ts          # Type definitions
│   └── storage.ts        # Storage utilities
├── dist/                 # Compiled output (generated)
├── package.json
├── tsconfig.json
└── README.md

Project ID

The server stores each project in ~/.mcp-architector/{projectId}/. projectId must be passed explicitly on every tool except list-projects.

• Call list-projects (with query = workspace folder name) to find the id
• MCP_PROJECT_ID is only a listing hint (isCurrent / suggestedProjectId), not a silent write target
• default-project and unsubstituted ${workspaceFolder} ids are forbidden

To start a new project, pass a stable id derived from the workspace path (e.g. _qs_my-app) to set-project-architecture.

Extending the Server

To add new tools, resources, or prompts, edit src/index.ts:

// Add a tool
server.registerTool(
  "tool-name",
  { /* tool config */ },
  async (params) => { /* handler */ }
);

// Add a resource
server.registerResource(
  "resource-name",
  new ResourceTemplate("uri-template", { /* options */ }),
  { /* resource config */ },
  async (uri, params) => { /* handler */ }
);

// Add a prompt
server.registerPrompt(
  "prompt-name",
  { /* prompt config */ },
  (args) => { /* handler */ }
);

License

MIT