Skip to main content
Glama
MCP Architector
by theSharque

MCP Architector

npm version GitHub

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.

Related MCP server: LocalNest MCP

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

Installs from npm registry automatically:

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

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

Available Tools

28 tools
delete-entriesDelete EntriesA

Bulk delete entries matching kind/moduleName/tags filter. Requires confirm=true. Use before full re-import or to clear a module slice. Prefer replace-entries with deleteOrphans for idempotent sync.

Inputs: confirm (required), projectId, kind, kinds, +2 more. Returns: deleted, message

delete-entryDelete EntryA

Removes one entry and updates the index. Use when a fact is obsolete. Do not use to delete modulesβ€”use delete-module. Cannot delete slice definitionsβ€”use delete-slice.

Inputs: id (required), projectId. Returns: message

delete-moduleDelete ModuleA

Deletes one module from architecture and its module detail file. Does not delete entriesβ€”remove those with delete-entry if needed. Does not delete custom slices.

Inputs: moduleName (required), projectId. Returns: message

delete-sliceDelete SliceA

Deletes a custom slice definition only. Built-in slices (api, domain, …) cannot be deleted. Does not delete entriesβ€”use delete-entry.

Inputs: sliceId (required), projectId. Returns: message

get-entryGet EntryA

Returns one full entry by id. Use after list-entries or search-entries when you need payload and refs. Do not use for a full API listβ€”use get-slice sliceId=api. Do not use for module structureβ€”use get-module-details.

Inputs: id (required), projectId. Returns: entry

get-import-statsGet Import StatsA

Returns entry counts grouped by kind, module, and tag. Use after replace-entries/import to verify catalog size.

Inputs: projectId. Returns: byKind, byModule, byTag, total

get-module-detailsGet Module DetailsA

Returns one module's full detail (files, dependencies, examples). Use when you know the module name from get-project-architecture or list-modules. If module has files but get-slice is empty, add entries with refs.moduleName=this module. For cross-cutting API/domain lists use get-slice. moduleName must match architecture exactly.

Inputs: moduleName (required), projectId. Returns: module

get-project-architectureGet Project ArchitectureA

Returns vertical structure: project description, module list, dataFlow. Use for refactoring boundaries between components. For all HTTP endpoints or domain terms use get-sliceβ€”not this tool. For one module's files and examples use get-module-details. projectId from list-projects if unsure.

Inputs: projectId. Returns: architecture

get-sliceGet SliceA

Returns a horizontal project view: filtered entries transformed for agents. Empty slice = no entries with matching kind. Call list-slices first to pick sliceId. format=compact default; table for api/ui slice. Use offset/limit for pagination. Filter further by moduleName or tags.

Inputs: sliceId (required), projectId, moduleName, tags, +5 more. Returns: slice

import-entriesImport EntriesA

Max 50 entries per bulk callβ€”split large catalogs into batches of ~50 to avoid oversized tool payloads. For full re-import: delete-entries once, then set-entries in 50-entry chunks; or replace-entries with deleteOrphans=false until the final batch (deleteOrphans=true). Alias for replace-entries (mode=replace). Pass filter as scope; send up to 50 entries per call.

Inputs: mode (required), filter (required), entries (required), projectId, +3 more. Returns: created, updated, deleted, entryIds, +1 more

list-entriesList EntriesA

Returns the entry catalog (id, kind, title, tags, moduleName)β€”no payload. Supports kind/moduleName/tags filters and pagination (limit max 200). Unlinked entries lack moduleName; run validate after edits. For typed horizontal views use get-slice.

Inputs: projectId, kind, moduleName, tags, +3 more. Returns: entries, total, returned, offset, +1 more

list-modulesList All ModulesA

Lists module summaries from architecture (name, description)β€”vertical structure only. For horizontal facts (endpoints, tables, terms) use list-slices then get-slice. After edits run validate. Use module names in set-entry refs.moduleName.

Inputs: projectId. Returns: modules

list-projectsList ProjectsA

Lists all projects in ~/.mcp-architector with projectId, description, moduleCount, updatedAt, isCurrent. Call first when tools return empty/wrong projectβ€”the workspace path may normalize to a different id (e.g. _qs_my-app). Then pass projectId to other tools. Optional query filters by id or description.

Inputs: query. Returns: projects

list-slicesList SlicesA

Lists built-in and custom slice views (filters over entriesβ€”not separate stored data). Empty slice = no entries with matching kind, not a missing slice definition. Use before get-slice to pick sliceId (api, domain, persistence, …).

Inputs: projectId. Returns: slices

rebuild-data-flowRebuild Data FlowB

Rebuilds dataFlow for all modules from module file dependencies or existing dependsOn edges. Recomputes providesTo and optionally syncs module files. Use instead of editing architecture.json directly.

Inputs: projectId, source, syncInverse, pruneOrphans. Returns: edgesAdded, edgesRemoved, modulesUpdated, message

rebuild-entry-indexRebuild Entry IndexA

Rebuilds entries/index.json from entry files on disk. Use when list-entries or get-slice miss entries that exist as files (index drift). Does not modify entry bodies.

Inputs: projectId. Returns: itemCount, message

refactor-architectureRefactor ArchitectureA

Preview or apply in-repo refactor sync to architector data (no workspace access). Default dryRun=true. Workflow: (1) scan with file/text to list hits, (2) build 1-3 mutation ops, (3) dryRun preview, (4) apply with dryRun=false and confirm=true. Mutations: move-file, replace-path-prefix, rename-text, patch-entry, merge-files, remove-file-ref. Orphan entries with empty refs.files and no entryIds are deleted. Does not change module names or dataFlow.

Inputs: operations (required), projectId, scope, dryRun, +3 more. Returns: dryRun, summary, stats, hits, +4 more

replace-entriesReplace EntriesA

Max 50 entries per bulk callβ€”split large catalogs into batches of ~50 to avoid oversized tool payloads. For full re-import: delete-entries once, then set-entries in 50-entry chunks; or replace-entries with deleteOrphans=false until the final batch (deleteOrphans=true). Idempotent sync for up to 50 entries in scope; optionally delete orphans not in this batch. Match by upsertBy (default kind+title). For large catalogs use deleteOrphans=false on intermediate batches, true only on the last batch.

Inputs: scope (required), entries (required), projectId, moduleName, +2 more. Returns: created, updated, deleted, entryIds, +1 more

search-entriesSearch EntriesA

Compact navigation search over entries by title, summary, kind, and tags. Returns snippet, matchedIn, slices, and moduleName per hitβ€”use get-entry for full payload. Prefer get-slice when you know the category (api, domain). Filters (moduleName, kind, tags) narrow agent context. Default limit 10.

Inputs: query (required), projectId, moduleName, kind, +3 more. Returns: summary, total, returned, offset, +2 more

set-entriesSet EntriesA

Entries need vertical structure: create modules via set-project-architecture / set-module-details before or when adding entries. Set refs.moduleName to an existing module name from list-modules. Run validate after edits to find entries-without-modules, entry-unlinked, or empty slices. Max 50 entries per bulk callβ€”split large catalogs into batches of ~50 to avoid oversized tool payloads. For full re-import: delete-entries once, then set-entries in 50-entry chunks; or replace-entries with deleteOrphans=false until the final batch (deleteOrphans=true). Set refs.moduleName per entry, or pass top-level moduleName as default. Prefer set-entries in 50-entry chunks over one huge replace-entries payload.

Inputs: entries (required), projectId, moduleName. Returns: entriesCreated, entriesUpdated, entryIds, message, +3 more

set-entrySet EntryA

Entries need vertical structure: create modules via set-project-architecture / set-module-details before or when adding entries. Set refs.moduleName to an existing module name from list-modules. Run validate after edits to find entries-without-modules, entry-unlinked, or empty slices. Creates or updates one canonical project fact (entry). Use when you discovered a concrete fact while working. Do not use for module structureβ€”use set-module-details. Do not copy module.description into summary; link via refs.moduleName only. Upsert: pass id to update, or omit id to match by kind+title or create new. Example: kind=http-endpoint, title='POST /orders', summary='Creates order', refs.moduleName='orders', refs.files=['src/OrderController.java'].

Inputs: kind (required), title (required), summary (required), projectId, +4 more. Returns: entryId, message, reminder, warning, +1 more

set-module-data-flowSet Module Data FlowA

Patches dataFlow for one module (dependsOn is canonical; providesTo is recomputed). Syncs module file dependencies. Prefer over set-project-architecture for single-module graph edits.

Inputs: moduleName (required), projectId, dependsOn, dataTransformation, +1 more. Returns: moduleName, message

set-module-detailsSet Module DetailsA

Creates or updates one vertical module (files, dependencies, dataFlow sync). IMPORTANT: Slices (api, domain, persistence) are built from entries, not from module text. When adding or updating a module, also add entries this module owns: pass facts[] (http-endpoint, entity, glossary, …) in this call (max 50 per call), or call set-entry / set-entries in 50-entry batches with refs.moduleName=. Max 50 entries per bulk callβ€”split large catalogs into batches of ~50 to avoid oversized tool payloads. For full re-import: delete-entries once, then set-entries in 50-entry chunks; or replace-entries with deleteOrphans=false until the final batch (deleteOrphans=true). Without entries, get-slice will be empty for this module. After edits call validate to verify links. Does not replace other modules. Prefer over set-project-architecture for single-module edits.

Inputs: name (required), description (required), inputs (required), outputs (required), +6 more. Returns: moduleId, message, entriesCreated, entriesUpdated, +3 more

set-project-architectureSet Project ArchitectureA

Creates or updates vertical module structure (components and dataFlow)β€”not horizontal facts. By default merges modules and dataFlow by name; omit dataFlow to keep existing flow. Use replaceModules or replaceDataFlow for full replace. For one module use set-module-details or set-module-data-flow. For bulk flow rebuild use rebuild-data-flow. Each new module still needs entriesβ€”use set-module-details with facts[] or set-entries after bulk structure. For APIs, domain terms, scripts use set-entry + get-sliceβ€”not this tool. If projectId is wrong, call list-projects first. Do not duplicate entry text in module descriptions.

Inputs: description (required), modules (required), projectId, dataFlow, +2 more. Returns: projectId, message

set-sliceSet SliceA

Saves a custom slice definition (filter onlyβ€”no items). Items always live in entries. Use when built-in slices (api, domain, …) are not enough, e.g. filter kinds godot-scene + tag gameplay. Do not store duplicate entry text here. get-slice reads entries through this filter.

Inputs: id (required), title (required), projectId, description, +2 more. Returns: sliceId, message

validateValidate ProjectA

Run after set-project-architecture, set-module-details, set-entry, or set-entries. Returns a compact report (summary, stats, issues by kind)β€”no need to load the full project in the agent. Checks only known rules: dataFlow consistency, module↔entry links, module detail files, entry index drift, empty api/domain/persistence slices, entry slice coverage, optional module-too-few-entries when moduleEntryMin is set. Fix issues[] then call validate again.

Inputs: projectId, checkInverse, checkModuleDeps, checkEntryCoverage, +5 more. Returns: projectId, valid, issueCount, summary, +5 more

validate-architectureValidate ArchitectureA

Alias for validate with the same checks. Prefer validate after edits. Legacy name kept for compatibility.

Inputs: projectId, checkInverse, checkModuleDeps, checkEntryCoverage, +5 more. Returns: projectId, valid, issueCount, summary, +5 more

validate-importValidate ImportA

Dry-run validation for a proposed import batch (max 50 entries). Max 50 entries per bulk callβ€”split large catalogs into batches of ~50 to avoid oversized tool payloads. For full re-import: delete-entries once, then set-entries in 50-entry chunks; or replace-entries with deleteOrphans=false until the final batch (deleteOrphans=true). Checks duplicate upsert keys and unknown moduleName refs without writing.

Inputs: entries (required), projectId, upsertBy, checkDuplicates, +1 more. Returns: valid, warningCount, warnings

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    Tools are well-described with distinct purposes, but the large number of entry manipulation tools (set-entry, set-entries, replace-entries, import-entries, delete-entry, delete-entries) could lead to confusion. However, descriptions clearly specify when to use each, making disambiguation possible with careful reading.

    Naming Consistency5/5

    All tools use a consistent verb_noun pattern in snake_case (e.g., list-entries, set-module-details, delete-slice). Related operations share prefixes (set-*, delete-*, list-*, get-*, validate-*), making the API predictable and easy to navigate.

    Tool Count4/5

    With 28 tools, the count is high but justified by the complexity of the domain (managing entries, modules, slices, projects, imports, validation, and bulk operations). Some redundancy (e.g., import-entries as alias for replace-entries) could be trimmed, but overall the tool set is well-scoped for a comprehensive architecture management server.

    Completeness5/5

    The tool set covers all essential operations: CRUD for entries, modules, slices, and projects; listing, searching, validation, bulk imports, data flow management, and refactoring. No obvious gaps are apparent; even edge cases like index drift and slice definition are addressed.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server providing persistent memory for AI coding assistants by storing and searching architectural decisions, patterns, and solutions. It also includes tools for git automation and mapping codebase expertise based on project history.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A local-first MCP server that provides AI agents with safe codebase access through file discovery, hybrid lexical-semantic search, and project introspection. It features durable local memory and semantic indexing while keeping all data and processing entirely on your local machine.
      74
      27 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides persistent memory and contextual awareness to language models, enabling project onboarding, recall of architectural rules, and code consistency across sessions.
      32
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A local-first MCP server providing secure workspace file operations, offline full-text search, and web search/fetch capabilities without requiring API keys.
      10
      -