briefmark-mcp 1.0.1

Universal MCP server for project documentation with smart classification

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