Skip to main content
Glama

Blueprint MCP

Blueprint gives AI coding agents a durable architecture memory for your repository.

It turns a codebase into a structured project map: responsibilities, relationships, entry points, risks, and the context an agent should read before changing code.

Instead of loading an entire repository into context, an agent can focus on the parts of the system that matter for the task. Developers also get a visual frontend for exploring the generated architecture map.

Use Blueprint when you want AI coding agents to work with less guesswork, tighter context, and a clearer understanding of how your project is actually put together.

Why Blueprint?

  • Gives agents a task-focused way to understand large codebases before editing.

  • Groups the system by responsibility, data flow, and ownership boundaries.

  • Produces detailed group documentation that agents can read selectively.

  • Reduces wasted context by routing each task to the most relevant project areas.

  • Keeps the architecture memory refreshable as the repository changes.

  • Provides a visual viewer so developers can inspect the same project map.

Blueprint does not replace source code as the source of truth. It gives both agents and developers a better starting point before they inspect the source.

Related MCP server: OpenLore

Install

npm install -g blueprint-mcp

Requires Node.js 20 or newer.

Global installation makes the blueprint command available in your shell:

blueprint open --watch

If you install Blueprint only inside a project with npm install blueprint-mcp, run it through an npm script or node_modules/.bin; local npm binaries are not added to your interactive shell path automatically.

MCP Configuration

Add Blueprint to your MCP client:

{
  "mcpServers": {
    "blueprint": {
      "command": "blueprint-mcp"
    }
  }
}

Restart your MCP client after changing the configuration.

Quick Start

Open your project in the coding agent you already use, such as Codex or Claude Code, and ask it to create a Blueprint:

Create a blueprint for this project.

The agent will scan the repository, group the codebase by responsibility, and write the architecture memory for future tasks.

Blueprint writes documentation in English by default. To use another language, ask for it naturally:

Create a Turkish blueprint for this project.

What It Creates

Blueprint writes local project memory under .blueprint/:

File

Purpose

brief.md

A compact routing index agents read first.

groups/*.md

Human-readable architecture notes for each project area.

blueprint-output.json

Structured project graph for tools and viewers.

refresh-scan.json

Filesystem snapshot used for deterministic refreshes.

Teams can decide whether to commit .blueprint/ or keep it local.

Tools

Tool

Purpose

blueprint.scan

Builds file inventory and code analysis artifacts.

blueprint.group

Prepares or applies semantic file grouping.

blueprint.compose

Writes the final Blueprint output and Markdown notes.

blueprint.refresh

Refreshes Blueprint state from the current filesystem snapshot.

blueprint.group.update

Assigns unassigned files or manages empty groups after refresh.

Viewer

Blueprint includes a static viewer for exploring generated memory. Open it in watch mode while working:

blueprint open --watch

Watch mode keeps the static viewer regenerated when Blueprint memory changes. If you only want to open the viewer once, remove --watch from the command.

Language Support

Blueprint uses Tree-sitter analysis for:

  • TypeScript / JavaScript

  • Python

  • Go

  • Rust

  • Java

Other files are still included in the inventory, but deeper symbol and import analysis depends on language support.

License

MIT

Available Tools

6 tools
blueprint.composeCompose Blueprint OutputA

Compose the final frontend-ready Blueprint JSON from a grouping artifact. If the response contains assistantNextSteps with required=true and executionPolicy=must_execute_before_final_response, the assistant must execute those steps before giving the user a final answer. For hydrate-group-docs, spawn one sub-agent per target group doc when sub-agents are available; otherwise edit the target docs yourself. Do not ask the user unless the required step is impossible.

ParametersJSON Schema
NameRequiredDescriptionDefault
groupingArtifactIdYesArtifact ID returned by blueprint.group apply mode
languageNoLanguage to use for Blueprint JSON summaries and group Markdown docs. Defaults to English.English

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully details behavioral traits: conditions for executing assistantNextSteps, sub-agent spawning for hydrate-group-docs, and the prohibition on asking the user unless impossible. This is highly transparent and actionable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no fluff. Purpose is front-loaded, behavioral instructions follow logically. Every sentence adds necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple parameter set (2 params, no nested objects, no output schema), the description covers the core function and provides comprehensive behavioral rules, making it sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing baseline info for both parameters. The description does not add new meaning beyond what the schema already states about groupingArtifactId and language.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly states the verb 'Compose' and the resource 'frontend-ready Blueprint JSON' from a grouping artifact, defining a distinct purpose that differentiates from sibling tools like blueprint.group, blueprint.scan, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description only provides internal behavioral instructions (e.g., how to handle assistantNextSteps and hydrate-group-docs), not tool selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blueprint.groupGroup Blueprint FilesA

Prepare mode returns a compact packet for semantic grouping; it is not the final grouping. The LLM should treat folder names as hints, not truth, and group by responsibility, runtime role, data flow, and dependencies. Prefer glob patterns like folder/** instead of enumerating files, and use exact file paths only for entry points, exceptions, or cross-cutting files. Apply mode consumes a small LLM-authored GroupingPlan and deterministically assigns files.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeYesprepare builds an LLM packet; apply validates and stores a grouping plan
analysisArtifactIdYesAnalysis artifact ID returned by blueprint.scan
planNoGrouping plan from the LLM. Required for apply mode.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that prepare does not finalize grouping and apply is deterministic, but it omits details like side effects (e.g., whether apply modifies data), authentication needs, rate limits, or error behavior. This is basic but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the main purpose. It efficiently covers both modes and includes key guidelines. Minor redundancy exists between the first and third sentences regarding apply mode, but overall it is well-structured and not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the two-mode complexity and absence of output schema, the description covers the basics but lacks details on return format (e.g., what the 'compact packet' contains) and prerequisites (e.g., need for a prior blueprint.scan). It provides adequate context for an LLM but leaves some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100% (all parameters described), so baseline is 3. The description adds value by explaining that 'plan' is required for apply mode and by providing usage hints that relate to parameter usage (e.g., using glob patterns for file paths). This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the two modes, 'prepare' and 'apply', with distinct purposes: prepare returns a compact packet for semantic grouping, apply consumes a GroupingPlan and assigns files. This verb-resource pairing is specific and distinguishes the tool from siblings, even without explicit comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance for prepare mode, instructing the LLM to treat folder names as hints and prefer glob patterns. It also notes that plan is required for apply mode. However, it does not contrast with sibling tools or specify when to use this tool versus alternatives, leaving room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blueprint.group.updateUpdate Blueprint GroupsA

Apply LLM group decisions after a Blueprint refresh. Use this tool only for assigning unassigned files to existing groups, creating a new group for unassigned files, or deleting groups that are already empty. Do not use this tool for updated files already assigned to a real group, deleted file cleanup, editing markdown memory, or rewriting blueprint-output.json manually. Validation rules: assignments[].fileId must refer to a file whose groupId is "unassigned"; assignments[].groupId must be an existing group id; newGroups[].id must not already exist; newGroups[].fileIds must all be unassigned file ids; deleteGroups[] may only contain groups with no fileIds. The tool writes .blueprint/blueprint-output.json and creates group markdown templates for new groups.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootYesAbsolute path to the project root
decisionYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool writes .blueprint/blueprint-output.json and creates group markdown templates, and implies state mutation. However, it does not mention error handling, side effects on existing groups, or backup behavior. With no annotations, the description carries the full burden and does fairly well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Reasonably concise given the complexity; front-loads purpose, then usage guidelines, then validation rules. Some redundancy (e.g., 'Do not use this tool for...' could be shortened) but overall well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the tool's output (files written) and validation rules, sufficient for a mutation tool. Lacks mention of return value or error states, but the core behavior is well described. With no output schema, the description does its job.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond the input schema by detailing validation rules for each field in the nested decision object (e.g., fileId must refer to unassigned, newGroups id must not exist). This compensates for the 50% schema coverage and makes parameters self-documenting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool applies LLM group decisions after a Blueprint refresh, specifying three allowed actions: assign unassigned files to existing groups, create new groups, and delete empty groups. It distinguishes from siblings by listing what not to use it for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (only for the three actions) and when not to use (e.g., updated files, deleted file cleanup, editing markdown). Validation rules provide clear constraints, making it easy for an agent to decide correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blueprint.refreshRefresh Blueprint DeterministicallyA

Deterministically refresh .blueprint/blueprint-output.json from the current filesystem snapshot. The tool compares .blueprint/refresh-scan.json with a fresh full scan, writes refreshed Blueprint JSON and scan state, and returns the maintenance prompt the assistant should follow. It does not send raw git diffs to the assistant. Use blueprint.group.update afterwards only for unassigned files or empty group decisions, then update affected group Markdown docs.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootYesAbsolute path to the project root
dryRunNoWhen true, compute the refresh result without writing blueprint files
changedPathsNoOptional changed paths used only as an update fallback when no previous hash snapshot exists
ignoreNoAdditional glob patterns to ignore during the filesystem scan
includeDefaultIgnoredNoWhen true, include default-ignored build, vendor, cache, and derived-output paths
maxFilesNoMaximum files to include in the inventory

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full behavioral disclosure. It describes side effects: writing blueprint files and scan state, and returning a maintenance prompt. It mentions comparison but does not explicitly state idempotence or whether it overwrites existing files, though 'refresh' implies that. Overall, it is transparent enough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences, front-loading the core action. It is efficient but slightly dense; no unnecessary words. Could benefit from clearer structure (e.g., bullet points) but still scores high on conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters with full schema coverage and no output schema, the description covers the tool's purpose, process, return value (maintenance prompt), and follow-up guidance. It lacks error or prerequisite info but is sufficiently complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add specific parameter details beyond the schema but provides process context (e.g., 'compares .blueprint/refresh-scan.json with a fresh full scan'). This is adequate but not extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Deterministically refresh .blueprint/blueprint-output.json from the current filesystem snapshot.' It explains the process (comparison and writing) and distinguishes itself from siblings by specifying a follow-up tool and what it does not do (no raw git diffs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises when to use blueprint.group.update afterwards and for what conditions ('only for unassigned files or empty group decisions'). It implies usage context by stating the tool is deterministic and does not send raw diffs, but it lacks explicit alternatives or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blueprint.scanScan Blueprint ProjectC

Public tool that builds a file inventory, analyzes parseable code, and returns the analysis artifact for grouping.

ParametersJSON Schema
NameRequiredDescriptionDefault
rootPathYesAbsolute path to repository root
ignoreNoAdditional glob patterns to ignore
includeDefaultIgnoredNoWhen true, include default-ignored build, vendor, cache, and derived-output paths
maxFilesNoMaximum files to include in the inventory

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behaviors. It fails to mention whether the tool is read-only, what side effects exist, or any authorization needs. The description is too sparse to inform the agent about behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loaded with the key action. However, the phrase 'Public tool' is slightly redundant and could be integrated better.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and 4 parameters, the description is too minimal. It does not explain what the 'analysis artifact' contains, nor does it address performance implications of maxFiles or ignore patterns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema already provides, which is acceptable given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool builds a file inventory, analyzes parseable code, and returns an analysis artifact. It implies a scanning purpose, but it does not explicitly differentiate from sibling tools like blueprint.refresh or blueprint.compose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The phrase 'for grouping' hints at a use case, but it does not provide clear when-to-use or when-not-to-use criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

blueprint.task_contextBuild Blueprint Task ContextB

Return a compact deterministic context slice for a natural-language task from a Blueprint output artifact.

ParametersJSON Schema
NameRequiredDescriptionDefault
blueprintArtifactIdYesArtifact ID returned by blueprint.compose
taskYesNatural-language task input to route through the Blueprint graph
maxPrimaryFilesNoMaximum primary files to return
maxSecondaryFilesNoMaximum secondary files to return
maxTestsNoMaximum likely test files to return
maxDocsNoMaximum Markdown docs to recommend reading

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits like idempotency, side effects, authorization needs, or determinism beyond the term 'deterministic' which is vague. The description adds minimal value beyond the input schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, efficiently conveying the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and 6 parameters, the description is too brief. It fails to explain the return value structure or behavior, leaving significant gaps in understanding for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond the parameter names and defaults, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and resource ('compact deterministic context slice from a Blueprint output artifact'), clearly distinguishing this tool from sibling tools like 'blueprint.compose' which likely creates a blueprint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no instructions on when to use this tool versus alternatives such as 'blueprint.scan' or 'blueprint.group', nor does it mention prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.3
    • First observedblueprint.compose
    • First observedblueprint.group
    • First observedblueprint.group.update
    • First observedblueprint.refresh
    • First observedblueprint.scan
    • First observedblueprint.task_context

TDQS

A3.8/5.0
Disambiguation5/5

Each tool targets a distinct operation: compose finalizes output, group handles semantic grouping, group.update applies post-refresh decisions, refresh updates from filesystem, scan builds inventory, and task_context retrieves context. No two tools overlap in purpose.

Naming Consistency5/5

All tools follow a consistent 'blueprint.<verb>' or 'blueprint.<verb>.<subverb>' pattern (e.g., blueprint.compose, blueprint.group.update). The naming is predictable and hierarchical.

Tool Count5/5

With 6 tools covering scanning, grouping, refreshing, composing, and context retrieval, the count is well-scoped for the domain of Blueprint artifact management. Each tool earns its place.

Completeness4/5

The set covers the core lifecycle: scan, group, update groups, refresh, compose final output, and retrieve task context. A minor gap is the lack of a tool to explicitly delete or list groups, but the workflow seems complete for typical use.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    Provides persistent architectural memory and structural cognition for AI coding agents, enabling efficient orientation, graph-aware context, and drift detection across codebase evolution.
    1,242
    297
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Provides a dependency graph of any local repository with tools for change impact, transitive dependents, health audits, and more, enabling AI coding agents to see structure and refactor safely.
    4,912
    4
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/engincankaya/blueprint'

If you have feedback or need assistance with the MCP directory API, please join our Discord server