BriefMark

Universal MCP server for project documentation
Human reads the same docs as LLM. LLM reads and updates them via MCP tools.

---

Install

pip install briefmark-mcp

Or with pipx (recommended for CLI tools):

pipx install briefmark-mcp

Or clone and install in development mode:

git clone https://github.com/VladYankovenko/BriefMark.git
cd BriefMark
pip install -e ".[dev]"

Quick Start

# Go to your project
cd ~/projects/my-app

# Initialize documentation structure
briefmark init

# Start the MCP server
briefmark serve

Features

• Single Source of Truth — one Docs/ folder for humans and AI
• Bidirectional — LLM can read AND write documentation via MCP tools
• Universal — works with any MCP-compatible agent (Cursor, Claude, Cline, Kimi)
• Lightweight — no external DB, no ML models, everything in project files
• Auto-Discovery — scans structure without config
• Frontmatter-native — documents declare their own metadata
• Section-level precision — read, edit, or delete one section without touching the rest
• Token-first — every tool returns estimated_tokens; agent sees operation cost
• Contextual search — search results include excerpts around the match + document outline

Project Structure

my-project/
├── .briefmark/
│   ├── config.json          # BriefMark config
│   └── .index.json          # Auto-generated search index (gitignored)
├── Docs/                    # Documentation root (user-managed structure)
└── .cursor/mcp.json         # Agent MCP config

Setup & Efficiency

BriefMark works out of the box, but project rules make it truly efficient.

Recommended workflow for your agent:

1. docs_search(query) — find relevant docs first
2. docs_read_section(path, section) — read only what you need
3. docs_update_section(path, section, content) — precise edits without full rewrites

Anti-pattern: docs_read + docs_write to change 1–2 sections — wastes tokens and risks collateral damage.

For detailed integration steps (Cursor, Claude, Kimi) and project rules templates, see Docs/Integration.md.

Document Format

Every document MUST have YAML frontmatter:

---
id: network-service
title: Network Service Pattern
category: pattern
summary: One-sentence description of what this document covers.
keywords: [network, api, alamofire]
---

# Network Service Pattern

## Motivation
...

## Implementation
...

Required fields: id, title, category, summary
Recommended: keywords (3–7 terms for search)

MCP Tools

Reading

Tool	Description
docs_read	Read full document content
docs_outline	Get heading structure (table of contents)
docs_read_section	Read a single section only
docs_list	List all documents with metadata
docs_search	Search docs by keyword

Writing

Tool	Description
docs_write	Create or overwrite a document
docs_update_frontmatter	Add or update frontmatter on existing file
docs_append	Append a section to the end
docs_update_section	Replace one section's body
docs_insert_section	Insert a new section after an existing one
docs_delete_section	Remove a section

Skills & Templates

Tool	Description
skill_list	List all available skills
skill_execute	Execute a skill with parameters
template_list	List available code templates
template_render	Render a template with variables

Agent Setup

Cursor

Copy to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "briefmark": {
      "command": "bash",
      "args": ["-lc", "briefmark serve"],
      "cwd": "${workspaceFolder}"
    }
  }
}

bash -lc ensures your shell PATH (conda, venv, pipx) is loaded — this works identically on any machine.

Claude Code

claude mcp add briefmark briefmark serve

Kimi Code / Open WebUI

Kimi Code CLI reads MCP config from the global ~/.kimi/mcp.json only — project-local .kimi-code/mcp.json is not auto-discovered.

See examples/kimi-code.md for setup instructions and multi-project configuration.

CLI Commands

Command	Description
briefmark serve	Start MCP server
briefmark init	Create Docs/ structure
briefmark index --rebuild	Rebuild search index
briefmark search <query>	Search documentation

License

MIT