Metadata-Version: 2.4
Name: briefmark-mcp
Version: 1.0.0
Summary: Universal MCP server for project documentation with smart classification
Project-URL: Homepage, https://github.com/VladYankovenko/BriefMark
Project-URL: Documentation, https://github.com/VladYankovenko/BriefMark#readme
Project-URL: Repository, https://github.com/VladYankovenko/BriefMark
Project-URL: Issues, https://github.com/VladYankovenko/BriefMark/issues
Author-email: Vlad Yankovenko <yankovenkomain@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,classification,claude,cursor,documentation,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: markdown>=3.5
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9.0
Requires-Dist: watchdog>=3.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" width="64" height="64" alt="BriefMark logo">
</p>

<h1 align="center">BriefMark</h1>

<p align="center">
  <strong>Universal MCP server for project documentation</strong><br>
  Human reads the same docs as LLM. LLM reads and updates them via MCP tools.
</p>

<p align="center">
  <a href="https://github.com/VladYankovenko/BriefMark/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
  </a>
  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/mcp-1.0+-green.svg" alt="MCP">
</p>

---

## Install

```bash
pip install git+ssh://git@github.com/VladYankovenko/BriefMark.git
```

Or clone and install in development mode:

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

## Quick Start

```bash
# 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](Docs/Integration.md).

## Document Format

Every document MUST have YAML frontmatter:

```markdown
---
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`:

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

```bash
claude mcp add briefmark briefmark serve
```

### Kimi Code / Open WebUI

See [`examples/kimi-code.md`](examples/kimi-code.md).

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