briefd
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BRIEFD_SOURCE | No | Knowledge repository: a git URL (https://…, git@…) or a directory. Optional for a smoke test; without it the server serves an empty index. | |
| BRIEFD_API_TOKEN | No | Bearer token for /mcp and /api. Empty means unauthenticated (only on trusted networks). | |
| BRIEFD_GIT_TOKEN | No | Token for private HTTPS git remotes. | |
| BRIEFD_FORGE_TYPE | No | github — opens a pull request for each propose_update. | |
| BRIEFD_FORGE_TOKEN | No | Forge API token with pull_requests:write. | |
| BRIEFD_SYNC_INTERVAL | No | How often the source is re-scanned; 0 disables polling. | 60s |
| BRIEFD_EMBEDDINGS_MODEL | No | Local model; all-MiniLM-L6-v2 is the English-only, faster alternative. | multilingual-e5-small |
| BRIEFD_DEFAULT_MAX_TOKENS | No | Default token budget for search_context and compile_bundle. | 2000 |
| BRIEFD_EMBEDDINGS_PROVIDER | No | local (pure-Go multilingual-e5-small, downloaded on first start), ollama, openai, or none for BM25-only. | local |
| BRIEFD_SYNC_WEBHOOK_SECRET | No | Enables POST /webhook/git (GitHub-style HMAC-SHA256) for immediate syncs. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
briefd serves your team's shared knowledge (domain rules, conventions, architecture decisions, project notes) on demand. Before writing code that could be affected by team rules, call compile_bundle with a short description of the task to get a budgeted context block, or search_context to inspect ranked sections. Pass scopes=["domain","conventions","projects/"] to include a project's own notes. Call get_document when you need a full document, and report_usage with the bundle_id and the chunk_ids that helped once you are done. If you find knowledge that is wrong or missing, propose_update creates a reviewable branch/PR — you never edit the knowledge directly.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| compile_bundleA | Compile what the team's knowledge base says about a task into one context block within a token budget. Call it once at the start of a task, before code that rules, conventions or past decisions could govern; describe the task in a sentence, not keywords. Sections are deduplicated, ordered domain → conventions → project, each with a source line (path, heading, last-updated date, and a note when the code it governs changed later). Read-only, deterministic, cached: same task, scopes and budget give the same bundle_id and content. Never exceeds max_tokens; a too-small budget truncates the top section with a marker. Afterwards, report which sections helped via report_usage. |
| get_documentA | Return one knowledge document in full (title, tags, the complete source file with front matter, its content_hash, last-updated date, and the documents it links to and is linked from) by the doc_path given in search or bundle results. Use it when a section is not enough, to follow a link, or before proposing an update: to edit a document, change source and pass the full result to propose_update with base_content_hash = content_hash. Read-only; not-found for unknown paths, forbidden outside the requested scopes. |
| list_scopesA | List the knowledge scopes this server holds — the shared 'domain' and 'conventions' scopes plus one 'projects/' per project — with document, section and token counts. Read-only, no input. Use it to discover the project scope to pass to search_context or compile_bundle; by default those search only the shared scopes. |
| propose_updateA | Propose a change to a knowledge document — fix an outdated rule, add a missing decision, create a document — for humans to review. Commits the complete new file to a git branch briefd/proposal- (and opens a pull request when a forge is configured); returns branch, commit and PR URL. Never changes what briefd serves until a human merges. Use it for knowledge that is wrong, stale ('code changed since' in bundles) or missing, not for scratch notes. To edit an existing document, call get_document, change its source and send the whole result with base_content_hash set to its content_hash; the call is refused if the file changed in the meantime or if the new content drops the front matter. Fails without a writable git source. |
| report_usageA | Record which sections of a compile_bundle result were actually useful for the task, by chunk_id. Optional, best called once after the task is done. An empty useful_chunk_ids list is meaningful: it marks the question as a knowledge gap for the people who maintain the repository. Stores feedback only; it does not change the current bundle or the ranking of this session. |
| search_contextA | Search the team's knowledge base (domain rules, conventions, decisions, project notes) and return the most relevant sections, ranked, within a token budget. Use it to look something up or see what exists; use compile_bundle when you want one context block for a task. Read-only. Each section carries its path, heading, scope, score and last-updated date; results never exceed max_tokens and say how many sections the budget omitted. |
| suggest_linksA | List links the knowledge base is missing: documents that mention another document by name without linking to it, and links whose target does not exist. Read-only. Use it when asked to tidy or connect the knowledge base, then fix the documents with propose_update (add [[wikilinks]] in the text or in a related: front-matter list). Suggestions a maintainer dismissed are left out. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool has a clearly distinct role: discovery (list_scopes), lookup (search_context), full read (get_document), task-scoped context (compile_bundle), write (propose_update), hygiene (suggest_links) and feedback (report_usage). The only potentially adjacent pair, search_context vs compile_bundle, is explicitly separated as 'look something up' versus 'one context block for a task', and descriptions reinforce each other.
All seven names follow a consistent snake_case verb_noun pattern (report_usage, get_document, propose_update, compile_bundle, list_scopes, search_context, suggest_links). Verbs are distinct and meaningful, with no camelCase or noun-only outliers.
Seven tools is well-scoped for a knowledge-base server, covering the read/discover/write/feedback lifecycle without redundancy. Each tool earns its place and none feels like filler.
The surface covers the core lifecycle: scope discovery, search, full document read, bundle compilation, proposed edits/creation, link cleanup, and usage feedback. Minor gaps remain: no way to delete or archive a document, and no explicit list/browse of documents within a scope (only counts), so agents must go through search to enumerate content.