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):

   bash

   Copy

   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

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.

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.