brief-mcp

The MCP server for BRIEF.md — a note taker while you chat, and a boot loader when you start a new session.

The Problem

When you plan a complex project in an AI chat, decisions get made, constraints get set, direction gets clear. As the conversation grows, the AI compacts it to manage the context window, keeping what it thinks matters — which isn't always what matters to you.

Starting a new session means re-explaining the project, or copying across old conversations, which fills the new context with stuff you don't need. Come back after a break and the same problem exists for you personally — the intent and decisions are somewhere in your head, or scattered across documents and chat histories.

How brief-mcp Solves This

As you chat, brief-mcp captures decisions, constraints, and open questions into a structured BRIEF.md file in the background. When you return to a project, it loads that context automatically — you start briefed, not blank.

Because BRIEF.md is just a file, any tool can read it. Planning in ChatGPT, coding in Cursor, reviewing in Claude — all referencing the same BRIEF.md. Instead of hunting through a lengthy chat history to find what actually matters, it's already distilled and ready.

README explains how a project works. BRIEF.md captures what it is and why it exists.

Features

• 57 MCP tools — full read/write access to BRIEF.md project context
• Hierarchy-aware context — walk upward through nested BRIEF.md files to build full context
• Ontology system — install, search, browse, and tag domain knowledge packs
• Reference system — bibliographic references with reverse index and suggestions
• Conflict detection — surface contradictions across decisions and constraints
• Type guides and extensions — domain-specific structure on top of a universal core
• Lifecycle tracking — maturity signals and phase-aware nudges
• Works with any domain — software, music, film, research, architecture, business — the core format extends to fit

Full documentation: See the docs/ directory for the complete manual including tool reference, interaction patterns, and guides.

Requirements

• Node.js >= 20.0.0

Installation

Important: The npm package is @brief-md/mcp, not brief-mcp. The unscoped brief-mcp on npm is an unrelated project.

npm install -g @brief-md/mcp

Or use directly with npx:

npx @brief-md/mcp

Quick Start

1. Add to your MCP client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "brief-mcp": {
      "command": "npx",
      "args": ["-y", "@brief-md/mcp"]
    }
  }
}

Claude Code:

claude mcp add brief-mcp -- npx --yes @brief-md/mcp

Cursor — Settings > MCP Servers, add:

{
  "brief-mcp": {
    "command": "npx",
    "args": ["-y", "@brief-md/mcp"]
  }
}

Windsurf — similar stdio configuration to Cursor.

2. Register a workspace

Tell the agent to register your projects directory:

"Add ~/projects as a brief-mcp workspace"

3. Create or re-enter a project

"Create a new BRIEF.md for my project" or "Re-enter my project"

The brief_reenter_project tool returns a structured summary — identity, decisions, questions, conflicts, lifecycle phase, and next steps — so the agent can pick up where you left off.

Tools

The server exposes 57 tools over MCP, organised by domain. See docs/tools/ for full parameter documentation and examples.

| Category | Tools | Description | |----------|-------|-------------| | Workspace & Session | 9 | Project creation, re-entry, workspace management | | Context Read | 4 | Read context, constraints, decisions, questions | | Context Write | 6 | Record decisions, questions, update sections | | Validation | 2 | Lint and conflict detection | | Hierarchy | 2 | Position and tree view | | Ontology | 17 | Search, browse, tag, install, create packs | | References | 5 | Add, lookup, suggest references | | Extensions & Type Guides | 9 | Extensions, type guides, structured sections | | Discovery & Analysis | 3 | Frameworks, maturity, registry search |

MCP Resource

| URI | Description | |-----|-------------| | brief://guide | AI interaction guide with 11 patterns, decision rules, and question rules |

Transport

brief-mcp communicates over stdio (JSON-RPC via stdin/stdout). The MCP client spawns the server as a subprocess — both must run on the same machine.

What this enables:

• Local use via Claude Desktop, Claude Code, Cursor, or any stdio MCP client
• Remote use via SSH or remote terminal (e.g. Claude Code over SSH)

What this does not enable:

• Direct network access from another machine or mobile device
• Running as a standalone persistent service

See docs/transport.md for remote access options and the HTTP transport roadmap.

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation, client setup, first project | | Core Concepts | BRIEF.md format, hierarchy, lifecycle, extensions | | Tool Reference | All 57 tools with parameters and examples | | Interaction Patterns | 11 patterns for AI-assisted workflows | | Decision Rules | DR-01 through DR-09 | | Question Rules | QUEST-01 through QUEST-12 | | Ontology System | Packs, tagging, structured sections | | Extensions | Built-in and custom extensions | | Type Guides | Domain-specific project templates | | Configuration | Config file, env vars, CLI flags | | Transport | stdio, remote access, HTTP roadmap | | Troubleshooting | Common issues and debugging |

Development

npm install          # Install dependencies
npm run build        # Build for production
npm test             # Run tests
npm run lint         # Lint (Biome)
npm run typecheck    # Type check (tsc)
npm run dev          # Watch mode

See CONTRIBUTING.md for development guidelines.

Security

See SECURITY.md for the vulnerability reporting policy and security design.

The server enforces path validation, input sanitisation, and resource limits on all operations. No external HTTP or AI API calls are made.

Community

• Code of Conduct
• Contributing
• Changelog

License

MIT