Docs / Reference / MCP Tools

MCP Tools Reference

Barrd exposes 43 tools to Claude via the Model Context Protocol. These are grouped by function: session management, tasks, documents, plans, decisions, code intelligence, and utilities.

Session management

Sessions are the core of Barrd's memory. They capture what you were working on, what decisions were made, and what's next.

load_session_state

Load the most recent session state for a project to resume work. Supports multiple retrieval strategies based on time decay and access patterns.

project_id required Project identifier (e.g., "my-project")
strategy "latest" (default), "relevant" (highest retrievability score), or "merge"
include_plan_context If true, includes plans, tasks with dependencies, documents, decisions, and smart suggestions. Adds ~15ms.
refresh_cache Force refresh plan context cache. Only applies when include_plan_context is true.

save_session_state

Save current session state for future continuity.

project_id required Project identifier
current_task_id Current task ID being worked on
current_plan_id Current plan ID
working_memory Working memory snapshot (JSON object)
context_snapshot Context snapshot — files modified, decisions, next steps (JSON object)

get_sessions

Query sessions for a project with filtering and sorting options.

project_id required
limit Maximum results (default: 50)

get_session

Retrieve a specific session by ID with full details.

session_id required

get_session_code_context

Retrieve AST data on-demand from the latest session. Complements the optimized load_session_state by providing full code context or specific file AST.

project_id required
file_path Specific file to retrieve. If omitted, returns all code context.

Projects

create_project

Create a new project or update if it already exists (upsert). Projects must be created before tasks, plans, or documents can be saved.

project_id required e.g., "my-app"
name required Human-readable name

Tasks

Tasks are auto-assigned IDs in PROJECT-NUMBER format (e.g., MY-APP-5). Statuses: todo, in_progress, blocked, done, cancelled. Priorities: P0–P3.

save_task

Create a new task. ID is auto-generated — do not provide task_id.

project_id required
title required
description
plan_id Link to a plan
type feature, bug, chore, research
status Default: todo
priority P0–P3
assigned_to

get_task

Get a specific task by ID.

task_id required

get_tasks

Query tasks with optional filters.

project_id required
status
priority
assigned_to

search_tasks

Search tasks by keywords in title or description. Returns results ranked by most recently updated.

project_id required
query required
limit Default: 10, max: 50

update_task_status

Quickly update task status without requiring all parameters.

task_id required
status required
assigned_to

update_task

Update an existing task's content or metadata. Only provided fields are updated.

task_id required
title, description, plan_id, type, status, priority, assigned_to, tags, details

task_dependency

Add or remove a dependency between tasks.

action required "add" or "remove"
task_id required Task that will be blocked
depends_on required Task that must complete first

get_task_chain

Get complete dependency chain showing upstream (blocking) and downstream (blocked) tasks transitively.

task_id required
direction "upstream", "downstream", or "both" (default)
max_depth Default: 10

add_progress_log

Add a progress log entry to a task.

task_id required
who required
what required

Documents

Markdown documents that can be linked to tasks. Types: guide, test_report, decision, architecture, plan_details, implementation, retrospective, general.

save_document

Create or update a markdown document.

document_id required
project_id required
title required
content required Markdown content
doc_type Default: guide
tags
linked_tasks Array of task IDs

get_document

Get a specific document by ID.

document_id required

get_documents

Query documents with optional filters.

project_id required
doc_type
tags
linked_task_id

update_document

Update an existing document. Only provided fields are updated.

document_id required
title, content, doc_type, tags

Plans

Plans group 3+ related tasks with a goal, approach, and success criteria.

save_plan

Create or update a plan.

plan_id required
project_id required
title required
status draft, in_progress, done, abandoned
problem What problem this solves
goal What you're achieving
approach Technical strategy
estimated_duration
tags

get_plan

Get a specific plan by ID, including linked tasks and progress.

plan_id required

get_plans

Query plans for a project.

project_id required
status

Decisions

save_decision

Record an architectural or design decision.

decision_id required
project_id required
title required
content JSON object with decision details, rationale, alternatives
status proposed, accepted, rejected, superseded
tags

get_decisions

Query decisions for a project.

project_id required
status
tags

Code intelligence

AST parsing (tree-sitter) and LSP integration for semantic code understanding. Supports Go, Rust, TypeScript, JavaScript, and Python.

parse_file_ast

Parse a source file using tree-sitter and extract its structure: functions, classes, imports, exports. Optionally uploads the result to Barrd for session context.

file_path required Absolute path to source file
project_id If provided, uploads AST to Barrd

analyze_file

Run semantic analysis on a file. Analyzer types: css (selectors, variables, media queries), react (components, hooks, props), concurrency (goroutines, channels, mutexes), interfaces (interface/trait definitions and implementations).

file_path required
analyzer required css, react, concurrency, interfaces

search_code_context

Search stored code context by symbol name, file path, or content. Uses the AST data uploaded by parse_file_ast.

project_id required
symbol_name
file_path
symbol_type function, struct, interface, etc.

read_symbol_lines

Read specific lines from a file, typically to view a symbol's implementation. Supports range format like src/main.rs:10-50.

location required file:start-end format

lsp

Query a language server for semantic code intelligence. Actions: definition (go to definition), references (find all usages), hover (type info and docs).

action required definition, references, hover
file_path required
line required
character required

lsp_workspace_symbols

Search for symbols across the entire workspace/project.

query required Symbol name to search for
language required go, rust, typescript, python

lsp_document_symbols

Get all symbols in a specific file via the language server.

file_path required

find_interface_implementations

Find all implementations of an interface or trait in a directory.

directory required
interface_name

CSS analysis

find_css_rules

Find CSS rules matching a selector pattern.

file_path required
pattern required Selector pattern to match (e.g., ".sidebar")

find_unused_selectors

Find CSS selectors not referenced in any component files.

css_path required
component_dir required

resolve_tailwind_classes

Resolve Tailwind utility classes to their CSS output.

classes required Array of class names

Knowledge graph

An entity relationship graph for connecting tasks, documents, decisions, and custom nodes.

add_graph_edge

Add a relationship between two entities in the graph.

project_id required
source_type required task, document, decision, etc.
source_id required
target_type required
target_id required
relation required e.g., "implements", "depends_on", "references"

query_graph

Query the knowledge graph by entity type, relation, or both.

project_id required
entity_type
relation

get_graph_neighbors

Get all entities connected to a given entity.

project_id required
entity_type required
entity_id required

Utilities

batch

Execute multiple tool calls in a single request. Each operation runs sequentially; failures don't abort the batch. Max 20 operations.

operations required Array of {tool, args} objects

get_template

Get a built-in Barrd template. Available: claude_md (CLAUDE.md template for new projects), template_guide (setup guide).

name required "claude_md" or "template_guide"

init_vector_db

Initialize the vector database index for a project's code context. Enables semantic search via query_context.

project_id required

query_context

Semantic search across stored code context. Requires init_vector_db to have been called first.

project_id required
query required
top_k Number of results (default: 5)

Next steps

Getting Started

Connect Barrd to Claude and create your first project.

→