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/

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

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

1. Install dependencies:

npm install

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

| list-slices | Built-in + custom slices with e