MCP Tools

The Contextia MCP server exposes 12 tools that AI agents can invoke on demand. These tools cover the full range of Contextia operations: reading artifacts, searching, assembling context, running checks, and managing session logs.

All tools return plain text in context format — compact, no ANSI codes, optimized for LLM consumption. Every tool reads from disk on each call (stateless per-call), so results always reflect the current state of the .contextia/ directory.

Artifact tools

These tools read and search Contextia artifacts: specs, decisions, norms, and other system knowledge.

mcp_show

Reads and displays a single artifact by its ID.

Parameter	Type	Required	Default	Description
artifact_id	string	yes	—	The artifact identifier (e.g., SPEC-012, DEC-006, NORM-003)
format	string	no	"summary"	Detail level: "meta", "summary", or "full"

Format levels:

• meta — frontmatter only (title, status, links, tags). Minimal token cost.
• summary — frontmatter plus the first section of the document body.
• full — the entire document, including all sections.

Returns: The artifact content at the requested detail level, or an error message if the artifact is not found.

Agent: mcp_show(artifact_id="SPEC-012", format="summary")

Response:
# SPEC-012: User Authentication Flow
status: approved
links: [DEC-003, NORM-001]
tags: [auth, security]
---
Users authenticate via OAuth 2.0 with PKCE. The system supports
Google and GitHub as identity providers. Session tokens are JWTs
with a 1-hour expiry and refresh token rotation.

mcp_search

Searches across artifacts by query string, with optional filters for type and field.

Parameter	Type	Required	Default	Description
query	string	yes	—	Search query (matched against title, tags, and body)
type	string	no	all	Filter by artifact type: "spec", "decision", "norm", "task"
field	string	no	all	Restrict search to a specific field: "title", "tags", "body"
limit	int	no	10	Maximum number of results to return

Returns: A list of matching artifacts with their ID, title, type, and relevance snippet.

Agent: mcp_search(query="authentication", type="spec", limit=5)

Response:
Found 2 specs matching "authentication":
1. SPEC-012: User Authentication Flow [auth, security]
2. SPEC-018: API Key Authentication [auth, api]

Tip

Search uses deterministic matching — exact substring and tag matching, not semantic similarity. If a search returns no results, try shorter or more specific terms.

mcp_list

Lists all artifacts of a given type, optionally filtered by status.

Parameter	Type	Required	Default	Description
type	string	yes	—	Artifact type: "spec", "decision", "norm", "task"
status	string	no	all	Filter by status (e.g., "approved", "draft", "deprecated")

Returns: A list of all matching artifacts with their ID, title, and status.

Agent: mcp_list(type="spec", status="approved")

Response:
12 approved specs:
- SPEC-001: Project Identity Schema [approved]
- SPEC-002: Config File Format [approved]
- SPEC-003: Frontmatter Validation Rules [approved]
...

mcp_trace

Shows the full traceability chain for a source file: which specs reference it, which annotations it contains, and which tasks involve it.

Parameter	Type	Required	Description
path	string	yes	Relative path to a source file (e.g., src/auth/login.py)

Returns: A traceability report showing all connections between the file and Contextia artifacts.

Agent: mcp_trace(path="src/auth/login.py")

Response:
Trace for src/auth/login.py:
  Annotations found:
    - @spec SPEC-012 (line 15, function: authenticate_user)
    - @spec SPEC-012.token-refresh (line 84, function: refresh_token)
    - @decision DEC-003 (line 23, function: authenticate_user)
  Referenced by specs:
    - SPEC-012: User Authentication Flow (paths: src/auth/*)
  Active tasks touching this file:
    - TASK-042: Implement token rotation

mcp_find_by_path

Finds all artifacts that reference a given file path, either through paths in frontmatter or through annotations in the source code.

Parameter	Type	Required	Description
file_path	string	yes	Relative path or glob pattern (e.g., src/auth/*.py)

Returns: A list of artifacts linked to the specified path.

Agent: mcp_find_by_path(file_path="src/auth/*.py")

Response:
Artifacts referencing src/auth/*.py:
- SPEC-012: User Authentication Flow (paths: src/auth/*)
- SPEC-018: API Key Authentication (paths: src/auth/api_keys.py)
- DEC-003: OAuth Provider Selection (paths: src/auth/oauth.py)

Context assembly

mcp_context

Assembles a complete context bundle for a task by following its links to specs, decisions, and norms. This is the primary tool for loading everything an agent needs to work on a task.

Parameter	Type	Required	Default	Description
task_id	string	yes	—	The task identifier (e.g., TASK-042)
depth	string	no	"summary"	Detail level for linked artifacts: "meta", "summary", "full"
budget	int	no	8000	Approximate token budget for the entire bundle

Returns: A structured context bundle containing the task, all linked specs, relevant decisions, applicable norms, and prior session logs — all within the token budget.

Agent: mcp_context(task_id="TASK-042", depth="summary", budget=6000)

Response:
## Context for TASK-042: Implement token rotation

### Task
status: in_progress
kind: feature
links: [SPEC-012, DEC-003]
...

### Linked Specs
#### SPEC-012: User Authentication Flow (summary)
...

### Linked Decisions
#### DEC-003: OAuth Provider Selection (summary)
...

### Applicable Norms
#### NORM-001: Security Requirements
...

### Prior Session Logs
Session 2026-02-28 (latest):
- Implemented basic token refresh
- Open question: rotation window length

Caution

The budget parameter is an approximation. Contextia estimates token counts heuristically (roughly 4 characters per token). The actual token count in your model’s tokenizer may differ slightly. Set the budget conservatively to leave room for the agent’s own reasoning.

Validation

mcp_check

Runs validation rules against the project and reports any issues: broken links, orphan specs, missing required fields, annotation mismatches.

Parameter	Type	Required	Default	Description
baseline	string	no	"all"	Which checks to run: "all", "links", "schema", "annotations"

Returns: A report listing all issues found, grouped by severity (error, warning, info).

Agent: mcp_check(baseline="links")

Response:
Link check results:
  2 errors:
    - SPEC-012 links to DEC-009 which does not exist
    - TASK-042 links to SPEC-099 which does not exist
  1 warning:
    - SPEC-005 is not linked to by any task (orphan spec)
  0 info

Task tools

These tools provide focused access to task artifacts in the work/tasks/ directory.

mcp_show_task

Reads a single task by ID. This is a convenience wrapper around mcp_show that defaults to the task type.

Parameter	Type	Required	Default	Description
task_id	string	yes	—	The task identifier (e.g., TASK-042)
format	string	no	"summary"	Detail level: "meta", "summary", "full"

Returns: The task content at the requested detail level.

Agent: mcp_show_task(task_id="TASK-042", format="full")

Response:
# TASK-042: Implement token rotation
status: in_progress
kind: feature
links: [SPEC-012, DEC-003]
assigned: agent
---
## Objective
Implement JWT refresh token rotation as specified in SPEC-012...

## Acceptance criteria
- Refresh tokens are single-use
- Old refresh tokens are invalidated after rotation
- Rotation window of 30 seconds for clock skew
...

mcp_list_tasks

Lists tasks with optional filters for status and kind.

Parameter	Type	Required	Default	Description
status	string	no	all	Filter by status: "backlog", "in_progress", "done", "blocked"
kind	string	no	all	Filter by kind: "feature", "bug", "chore", "spike"

Returns: A list of matching tasks with their ID, title, status, and kind.

Agent: mcp_list_tasks(status="in_progress")

Response:
3 in_progress tasks:
- TASK-042: Implement token rotation [feature, in_progress]
- TASK-045: Fix session expiry race condition [bug, in_progress]
- TASK-048: Add rate limiting config [chore, in_progress]

Session log tools

Session logs track what an agent did during a work session: decisions made, files changed, open questions. These three tools manage the log lifecycle.

mcp_read_log

Reads session logs for a task.

Parameter	Type	Required	Default	Description
task_id	string	yes	—	The task identifier
latest	bool	no	true	If true, return only the most recent log entry
n	int	no	1	Number of recent log entries to return (ignored if latest is true)

Returns: The requested session log entries, most recent first.

Agent: mcp_read_log(task_id="TASK-042", latest=true)

Response:
Session log for TASK-042 (2026-02-28T14:30:00Z):
  status: closed
  ## Summary
  Implemented basic token refresh mechanism in src/auth/refresh.py.
  Added unit tests covering the happy path and expired token case.
  ## Open questions
  - What should the rotation window be? SPEC-012 says 30s but DEC-003
    mentions "configurable" without specifying a default.
  ## Files changed
  - src/auth/refresh.py (new)
  - tests/auth/test_refresh.py (new)

mcp_write_log

Writes or appends to the current session log for a task. The agent calls this periodically during work to record progress.

Parameter	Type	Required	Description
task_id	string	yes	The task identifier

Note

The log content is provided in the tool call body as structured text. The server timestamps the entry automatically and appends it to the current session’s log file at work/active/{task_id}/logs/.

Agent: mcp_write_log(task_id="TASK-042")
Body:
  ## Progress
  - Added rotation window configuration to config.yaml schema
  - Updated SPEC-012 proposal with configurable window default (30s)
  ## Decisions
  - Chose 30s as default rotation window based on OAuth 2.0 BCP

Response:
Log entry written to TASK-042 session 2026-03-01T10:15:00Z

mcp_close_log

Closes the current session log for a task, marking it as complete. After closing, a new mcp_write_log call will start a fresh session.

Parameter	Type	Required	Description
task_id	string	yes	The task identifier

Returns: Confirmation that the session log was closed.

Agent: mcp_close_log(task_id="TASK-042")

Response:
Session log closed for TASK-042 (2026-03-01T11:00:00Z)
Duration: 45 minutes
Entries: 3

Error handling

All tools follow a consistent error pattern. When a tool encounters a problem, it returns a plain-text error message rather than raising an exception. The agent can inspect the message and decide how to proceed.

Common error patterns:

Situation	Response
Artifact not found	"Artifact SPEC-099 not found. Available specs: SPEC-001..SPEC-048"
Invalid parameter	"Invalid type 'module'. Valid types: spec, decision, norm, task"
No project found	"No Contextia project found in /path/to/cwd or any parent. Run contextia init to create one."
Malformed frontmatter	"Error reading SPEC-012: missing required field 'status' in frontmatter"