MCP Reference

Complete reference for all 58 tools exposed by the Jig MCP server.

Connect with: jig serve mcp (stdio transport).

Note: Most tools accept an optional project parameter (string) to target a specific project. If omitted, the active session project is used. This parameter is listed where relevant but omitted from simple tools for brevity.

Project setup

list_projects / switch_project / create_project / delete_project

Spec authoring

list_specs / show_spec / create_spec / update_spec
reparent_spec / archive_spec / delete_spec

Task management

list_tasks / show_task / create_task / update_task
delete_task / move_task / verify_task

Criteria

add_criterion / list_criteria / remove_criterion

Execution and planning

decompose / next_tasks / plan_parallel
show_status / show_tree
list_runs / show_run

Context bundles

list_bundles / show_bundle / create_bundle / update_bundle / delete_bundle

Snippets

list_snippets / show_snippet / create_snippet / delete_snippet

Requests

create_request / list_requests / show_request
link_to_request / resolve_request / search_requests

Intake

file_bug / file_idea / list_findings / dismiss_finding

Attachments

add_attachment / list_attachments

Decisions

record_decision / list_decisions

Sharing

share_spec / unshare_spec / list_shares

Briefing

get_briefing

Utilities

search / workflow_guide

list_projects

List all registered projects with their spec count and health. Shows which project is currently active.

Parameters: none

Example:

list_projects()

Example output:

Projects:
  * my-app      4 specs  healthy
    api-server  2 specs  healthy

(* = active project)

switch_project

Set the active project for this session. All subsequent tools operate on the selected project until you switch again.

Parameters:

Name	Type	Description
`name`	string	Project name to switch to

Example:

switch_project({ name: "my-app" })

create_project

Create a new Jig project for a repository. Automatically selects the new project as the active session project.

Parameters:

Name	Type	Description
`name`	string	Project name (typically the repository or codebase name)
`description`	string (optional)	Short description of what this project is for

Example:

create_project({ name: "my-app", description: "Main web application" })

delete_project

Permanently delete a project and all its specs, tasks, and runs. This action cannot be undone.

Parameters:

Name	Type	Description
`name`	string	Project name to delete

Example:

delete_project({ name: "old-prototype" })

list_specs

List all feature specs with status and task counts in a hierarchical tree showing parent/child relationships. Archived specs are hidden by default.

Parameters:

Name	Type	Description
`include_archived`	boolean (optional)	Include archived specs (default false)

Example:

list_specs()
list_specs({ include_archived: true })

Example output:

[in-progress] auth-layer  (3/5 tasks)
  [new]  login-flow  (0/2 tasks)
[done]   database-client  (2/2 tasks)

show_spec

Show a spec’s full markdown content and list of associated tasks with their status.

Parameters:

Name	Type	Description
`name`	string	Spec name

Example:

show_spec({ name: "auth-layer" })

create_spec

Create a new spec from template. Before calling this, run the Spec Placement Protocol: call list_specs first, classify the work, and confirm placement with the user.

Parameters:

Name	Type	Description
`name`	string	Spec name in kebab-case
`layer`	`"platform"` \| `"services"` \| `"surface"` (optional)	Architectural layer
`parent`	string (optional)	Parent spec name for sub-specs

Example:

create_spec({ name: "auth-layer", layer: "platform" })
create_spec({ name: "login-flow", parent: "auth-layer" })

update_spec

Update a spec’s content or metadata. Supports two modes: content replacement (full markdown) and patch mode (individual fields). Cannot combine both modes in a single call.

Parameters:

Name	Type	Description
`name`	string	Spec name
`content`	string (optional)	Full markdown content (content replacement mode)
`bundle_names`	string[] (optional)	Context bundle names to reference during decomposition and execution
`layer`	`"platform"` \| `"services"` \| `"surface"` (optional)	Architectural layer (patch mode)
`stage`	string (optional)	Spec stage (patch mode)
`parent`	string \| null (optional)	Parent spec name, or null to make top-level (patch mode)
`bundles`	string[] (optional)	Context bundle names to associate (patch mode, alias for bundle_names)

Example:

update_spec({
  name: "auth-layer",
  content: "# Feature: auth-layer\n\n## Intent\n\nHandles authentication..."
})
update_spec({ name: "auth-layer", layer: "platform", stage: "in-progress" })

reparent_spec

Move a spec under a different parent or make it top-level. Pass null as new_parent to promote to top-level. Prevents circular references.

Parameters:

Name	Type	Description
`name`	string	Spec name to reparent
`new_parent`	string \| null	New parent spec name, or null for top-level

Example:

reparent_spec({ name: "login-flow", new_parent: "user-auth" })
reparent_spec({ name: "login-flow", new_parent: null })

archive_spec

Archive a spec, hiding it from default list_specs and show_status views. The spec still exists and can be found with include_archived.

Parameters:

Name	Type	Description
`name`	string	Spec name to archive

Example:

archive_spec({ name: "old-feature" })

delete_spec

Hard-delete a spec and all its tasks. Refuses if the spec has sub-specs (delete children first).

Parameters:

Name	Type	Description
`name`	string	Spec name to delete

Example:

delete_spec({ name: "old-feature" })

list_tasks

List all tasks for a spec with IDs, objectives, and status.

Parameters:

Name	Type	Description
`spec`	string	Spec name

Example:

list_tasks({ spec: "auth-layer" })

Example output:

[passed]      setup-auth-client: Create the Supabase auth client singleton
[in-progress] implement-token-refresh: Add silent token refresh middleware
[new]         add-session-guard: Protect routes with session check

show_task

Show a task’s full YAML content including objective, intent, file scope, verification gates, dependencies, and status. Supports both spec+task and handle-based lookup.

Parameters:

Name	Type	Description
`spec`	string (optional)	Spec name (not needed if using handle)
`task`	string (optional)	Task name or handle (e.g., `kex-42`)
`handle`	string (optional)	Task handle — alternative to spec+task

Example:

show_task({ spec: "auth-layer", task: "setup-auth-client" })
show_task({ handle: "kex-42" })

create_task

Create a new task for a spec. Every task must have objective, file_scope, and at least one behavioral verification command. For tasks involving migrations or deployments, include structured criteria with environment: "production".

Parameters:

Name	Type	Description
`spec`	string	Spec name
`task`	string	Task name in kebab-case
`fields`	object	Task fields (see below)

fields object:

Field	Type	Description
`objective`	string	One-sentence goal
`intent`	string (optional)	Why this task exists: current state, reasoning, expected impact
`context`	string (optional)	Architectural background
`acceptance_criteria`	array (optional)	Plain strings or structured SAP criteria with subject/property/expected/method
`file_scope`	string[] (optional)	Files this task creates or modifies (1-5 files)
`verification`	array (optional)	Commands that prove completion — each has `command` and `proves`
`guardrails`	string[] (optional)	What NOT to do
`complexity`	`"simple"` \| `"moderate"` \| `"complex"` (optional)	Task complexity
`dependencies`	string[] (optional)	Task names that must complete first

Example:

create_task({
  spec: "auth-layer",
  task: "setup-auth-client",
  fields: {
    objective: "Create the Supabase auth client singleton",
    intent: "Components currently init Supabase inline. Centralizing removes duplication.",
    file_scope: ["src/auth/client.ts", "src/components/Login.tsx"],
    verification: [
      { command: "bun run typecheck", proves: "No TypeScript errors" },
      { command: "bun test src/auth", proves: "Auth client works correctly" }
    ],
    guardrails: ["Do not change Supabase project URL or anon key"],
    complexity: "simple"
  }
})

update_task

Update task fields such as status, objective, or verification gates. Always include completion_notes when marking a task as passed or failed. Blocked status requires blocked_reason. Supports handle-based lookup.

Parameters:

Name	Type	Description
`spec`	string (optional)	Spec name (not needed if using handle)
`task`	string (optional)	Task name or handle (e.g., `kex-42`)
`handle`	string (optional)	Task handle — alternative to spec+task
`fields`	object	Fields to update (key-value pairs)

Example:

update_task({
  spec: "auth-layer",
  task: "setup-auth-client",
  fields: {
    status: "passed",
    completion_notes: "Created src/auth/client.ts singleton. Updated Login.tsx and Profile.tsx."
  }
})
update_task({
  handle: "kex-42",
  fields: { status: "blocked", blocked_reason: "Waiting on database migration" }
})

delete_task

Hard-delete a task from a spec. Tasks that depended on this one have their dependency removed (with a warning).

Parameters:

Name	Type	Description
`spec`	string	Spec name
`task`	string	Task name to delete

Example:

delete_task({ spec: "auth-layer", task: "setup-auth-client" })

move_task

Move a task from one spec to another, preserving all content.

Parameters:

Name	Type	Description
`spec`	string	Current spec name
`task`	string	Task name to move
`target_spec`	string	Target spec name

Example:

move_task({ spec: "auth-layer", task: "setup-auth-client", target_spec: "database-client" })

verify_task

Run a task’s verification gates as a third-party check. Executes each verification command and automatically passes or fails the task based on the results. Supports handle-based lookup.

Parameters:

Name	Type	Description
`spec`	string (optional)	Spec name (not needed if using handle)
`task`	string (optional)	Task name or handle
`handle`	string (optional)	Task handle — alternative to spec+task

Example:

verify_task({ spec: "auth-layer", task: "setup-auth-client" })
verify_task({ handle: "kex-42" })

Example output:

Verification PASSED (2/2)
Verified by: mcp

o bun run typecheck
o bun test src/auth

add_criterion

Add a structured acceptance criterion to a task with an auto-generated verification method. Uses the SAP (Structured Acceptance Protocol) format.

Parameters:

Name	Type	Description
`task`	string	Task name
`subject`	string	What to check (file path, URL, command, DB table)
`property`	enum	`"contains_string"`, `"not_contains"`, `"file_exists"`, `"http_status"`, `"column_exists"`, `"output_matches"`, `"count_gte"`, `"schema_matches"`
`expected`	string	Expected value or pattern
`description`	string	Human-readable description of the criterion

Example:

add_criterion({
  task: "setup-auth-client",
  subject: "src/auth/client.ts",
  property: "file_exists",
  expected: "true",
  description: "Auth client module exists"
})

list_criteria

List a task’s acceptance criteria with subjects, properties, and verification methods.

Parameters:

Name	Type	Description
`task`	string	Task name

Example:

list_criteria({ task: "setup-auth-client" })

remove_criterion

Remove a criterion from a task. The criterion is soft-deleted and preserved in history.

Parameters:

Name	Type	Description
`criterion_id`	string	The criterion UUID to remove

Example:

remove_criterion({ criterion_id: "abc123-def456" })

list_runs

List execution runs for a spec, showing result status and duration.

Parameters:

Name	Type	Description
`spec`	string	Spec name

Example:

list_runs({ spec: "auth-layer" })

Example output:

[passed]  run-001  setup-auth-client  12.3s
[failed]  run-002  implement-token-refresh  8.1s

show_run

Show a run’s full output including task output, verification results, and result status.

Parameters:

Name	Type	Description
`spec`	string	Spec name
`run_id`	string	Run ID

Example:

show_run({ spec: "auth-layer", run_id: "run-001" })

decompose

Return structured spec content (intent, criteria, constraints, bundles, existing tasks) for task decomposition. Create tasks from the result via create_task.

Parameters:

Name	Type	Description
`spec`	string	Spec name

Example:

decompose({ spec: "auth-layer" })

Note: In conversational workflows with Claude, prefer decomposing in-conversation with create_task calls rather than using this tool. The decompose tool is intended for CLI and headless use.

next_tasks

Return dependency-ready tasks ordered by wave, unlock power, and priority. Use parallel to get N conflict-free tasks safe for simultaneous execution. Use request_id to filter tasks linked to a specific request.

Parameters:

Name	Type	Description
`spec`	string (optional)	Filter by spec
`count`	number (optional)	Max tasks to return (default 10)
`parallel`	number (optional)	Return N conflict-free tasks safe to run in parallel (checks file_scope overlaps)
`request_id`	string (optional)	Filter tasks to only those linked to a specific request

Example:

next_tasks()
next_tasks({ spec: "auth-layer", count: 3 })
next_tasks({ parallel: 4 })
next_tasks({ request_id: "req-abc123" })

plan_parallel

Compute optimal parallel execution batches respecting dependencies and file scope overlap. Shows all waves of tasks that can be executed simultaneously.

Parameters:

Name	Type	Description
`spec`	string (optional)	Limit plan to a specific spec

Example:

plan_parallel()
plan_parallel({ spec: "auth-layer" })

show_status

Show project status overview, or drill into a specific spec to see individual task progress.

Parameters:

Name	Type	Description
`spec`	string (optional)	Spec name for detail view

Example:

show_status()
show_status({ spec: "auth-layer" })

show_tree

Return the full project skeleton: specs with sub-specs and tasks, all with status indicators. Hierarchical view for understanding project structure at a glance.

Parameters:

Name	Type	Description
`spec`	string (optional)	Show tree for a single spec and its children

Example:

show_tree()
show_tree({ spec: "auth-layer" })

Example output:

auth-layer [in-progress]
  login-flow [new]
    setup-oauth-redirect [new]
    handle-callback [new]
  setup-auth-client [passed]
  implement-token-refresh [in-progress]

list_bundles

List available context bundles. Filter with flags to control shared/project-only visibility.

Parameters:

Name	Type	Description
`include_shared`	boolean (optional)	Include shared bundles from other projects (default false)
`shared_only`	boolean (optional)	Show only shared bundles (cross-project)
`project_only`	boolean (optional)	Show only project bundles, exclude shared

Example:

list_bundles()
list_bundles({ include_shared: true })
list_bundles({ shared_only: true })

show_bundle

Show a context bundle’s full content including files, constraints, patterns, and shared status.

Parameters:

Name	Type	Description
`name`	string	Bundle name

Example:

show_bundle({ name: "api-client-patterns" })

create_bundle

Create a new reusable context bundle for sharing files, constraints, and patterns across specs. Use update_bundle to add content after creating.

Parameters:

Name	Type	Description
`name`	string	Bundle name (kebab-case)
`description`	string (optional)	Bundle description
`is_shared`	boolean (optional)	Make bundle available across all projects (default false)

Example:

create_bundle({ name: "api-client-patterns" })
create_bundle({ name: "shared-conventions", description: "Cross-project coding standards", is_shared: true })

update_bundle

Update a bundle’s files, constraints, patterns, description, or shared status. Pass only the fields you want to change.

Parameters:

Name	Type	Description
`name`	string	Bundle name
`fields`	object	Fields to update (see below)

fields object:

Field	Type	Description
`description`	string (optional)	New bundle description
`files`	array (optional)	Files included: each has `path` and optional `reason`
`constraints`	string[] (optional)	Implementation constraints
`patterns`	array (optional)	Code patterns: each has `name` and optional `description`
`is_shared`	boolean (optional)	Make bundle available across all projects

Example:

update_bundle({
  name: "api-client-patterns",
  fields: {
    files: [
      { path: "src/api/client.ts", reason: "Base HTTP client" },
      { path: "src/api/types.ts", reason: "Shared API types" }
    ],
    constraints: ["All API calls must go through the client singleton"],
    patterns: [{ name: "retry-with-backoff", description: "Exponential backoff on 5xx" }]
  }
})

delete_bundle

Delete a context bundle permanently. Only deletes bundles owned by the current project.

Parameters:

Name	Type	Description
`name`	string	Bundle name

Example:

delete_bundle({ name: "old-patterns" })

list_snippets

List available text snippets. Use include_shared to see cross-project snippets.

Parameters:

Name	Type	Description
`include_shared`	boolean (optional)	Include shared snippets from other projects (default false)

Example:

list_snippets()
list_snippets({ include_shared: true })

show_snippet

Show a snippet’s full text content.

Parameters:

Name	Type	Description
`name`	string	Snippet name

Example:

show_snippet({ name: "auth-setup-steps" })

create_snippet

Create a named reusable text snippet. Use is_shared for cross-project availability.

Parameters:

Name	Type	Description
`name`	string	Snippet name (kebab-case)
`content`	string	The text content of the snippet
`is_shared`	boolean (optional)	Make snippet available across all projects (default false)

Example:

create_snippet({
  name: "auth-setup-steps",
  content: "1. Create Supabase client\n2. Configure auth providers\n3. Add session middleware"
})

delete_snippet

Delete a snippet permanently. Only affects snippets owned by the current project.

Parameters:

Name	Type	Description
`name`	string	Snippet name

Example:

delete_snippet({ name: "old-snippet" })

create_request

Create a request to track work originating from conversations, bugs, ideas, or internal needs. Requests capture intent before any spec or task exists.

Parameters:

Name	Type	Description
`title`	string	Short title summarizing the request
`description`	string (optional)	Detailed description of the request
`origin`	enum (optional)	`"conversation"`, `"bug"`, `"idea"`, `"user-report"`, `"internal"` (default: `"internal"`)
`priority`	enum (optional)	`"critical"`, `"high"`, `"normal"`, `"low"` (default: `"normal"`)

Example:

create_request({
  title: "Add focus mode for single-phrase editing",
  description: "Users want to isolate a single phrase for focused editing without distraction from other content.",
  origin: "user-report",
  priority: "high"
})

list_requests

List requests with optional status and priority filters. Ordered by most recent.

Parameters:

Name	Type	Description
`status`	enum (optional)	`"open"`, `"in-progress"`, `"resolved"`, `"abandoned"`, `"deferred"`
`priority`	enum (optional)	`"critical"`, `"high"`, `"normal"`, `"low"`

Example:

list_requests()
list_requests({ status: "open", priority: "high" })

show_request

Show a request’s full details including linked tasks, findings, and specs.

Parameters:

Name	Type	Description
`request_id`	string	Request UUID

Example:

show_request({ request_id: "abc123-def456" })

link_to_request

Link a task, finding, or spec to a request. Tasks use spec_name/task_name format for the link target.

Parameters:

Name	Type	Description
`request_id`	string	Request UUID to link to
`link_type`	enum	`"task"`, `"finding"`, `"spec"`
`link_target`	string	Target identifier: `spec_name/task_name` for tasks, finding ID for findings, spec name for specs

Example:

link_to_request({
  request_id: "abc123-def456",
  link_type: "spec",
  link_target: "focus-mode"
})
link_to_request({
  request_id: "abc123-def456",
  link_type: "task",
  link_target: "focus-mode/setup-focus-state"
})

resolve_request

Resolve a request with an outcome and a required learning. Records the resolution timestamp.

Parameters:

Name	Type	Description
`request_id`	string	Request UUID to resolve
`outcome`	enum	`"resolved"`, `"partial"`, `"deferred"`, `"wont-fix"`, `"cant-reproduce"`
`learning`	string	What was learned from this request (required)
`outcome_notes`	string (optional)	Additional notes about the resolution

Example:

resolve_request({
  request_id: "abc123-def456",
  outcome: "resolved",
  learning: "Focus mode requires isolating the phrase panel from the canvas scroll context."
})

search_requests

Search requests by title or description text. Returns matches ordered by most recent.

Parameters:

Name	Type	Description
`query`	string	Search text to match against request titles and descriptions

Example:

search_requests({ query: "focus mode" })

file_bug

File a bug report into the intake pile. AI triage runs in the background to match it to the most relevant spec.

Parameters:

Name	Type	Description
`content`	string	Description of the bug
`context`	string (optional)	Additional context from the conversation

Example:

file_bug({
  content: "Login button does nothing when clicked on mobile Safari",
  context: "User reported this in their iOS 17 session, using Safari 17"
})

Example output:

{
  "id": "bug-3a9f",
  "type": "bug",
  "status": "new",
  "content": "Login button does nothing when clicked on mobile Safari",
  "created_at": "2026-03-03T14:22:00Z"
}

file_idea

File a feature idea into the intake pile. AI triage runs in the background to match it to the most relevant spec.

Parameters:

Name	Type	Description
`content`	string	Description of the idea
`context`	string (optional)	Additional context from the conversation

Example:

file_idea({
  content: "Let users pin their most-used specs to the top of the list"
})

list_findings

List findings from the intake pile. Shows bugs and ideas with triage status, suggested spec, and severity. Defaults to non-dismissed, newest first.

Parameters:

Name	Type	Description
`pile_type`	`"bug"` \| `"idea"` (optional)	Filter by type
`status`	`"new"` \| `"triaged"` \| `"planned"` \| `"dismissed"` (optional)	Filter by status
`limit`	number (optional)	Max results (default 20)

Example:

list_findings()
list_findings({ pile_type: "bug", limit: 5 })

dismiss_finding

Dismiss a finding so it no longer appears in default listings.

Parameters:

Name	Type	Description
`finding_id`	string	ID of the finding to dismiss

Example:

dismiss_finding({ finding_id: "bug-3a9f" })

add_attachment

Attach text content (logs, snippets, notes) to a task, spec, finding, or project.

Parameters:

Name	Type	Description
`parent_type`	enum	`"task"`, `"spec"`, `"finding"`, `"project"`
`parent_id`	string	Parent entity ID (task name, spec name, etc.)
`name`	string	Attachment name (e.g., `error-log`, `screenshot-1`)
`content`	string (optional)	Inline text content (for snippets, logs, etc.)
`attachment_type`	string (optional)	Type: `snippet`, `log`, `image`, `file` (default: `snippet`)
`mime_type`	string (optional)	MIME type (default: `text/plain`)

Example:

add_attachment({
  parent_type: "task",
  parent_id: "setup-auth-client",
  name: "error-log",
  content: "TypeError: Cannot read property 'session' of undefined\n  at AuthClient.init (client.ts:42)",
  attachment_type: "log"
})

list_attachments

List attachments for a task, spec, finding, or project.

Parameters:

Name	Type	Description
`parent_type`	enum	`"task"`, `"spec"`, `"finding"`, `"project"`
`parent_id`	string	Parent entity ID

Example:

list_attachments({ parent_type: "task", parent_id: "setup-auth-client" })

Example output:

Attachments for task "setup-auth-client":
- error-log [log] (0.2KB) | Preview: TypeError: Cannot read property...
- design-notes [snippet] (1.4KB) | Preview: The auth client should...

record_decision

Record a decision on a task with decision text and rationale. Sets the task status to passed.

Parameters:

Name	Type	Description
`spec`	string	Spec name
`task`	string	Task name
`decision_text`	string	What was decided
`rationale`	string	Why this decision was made (required)

Example:

record_decision({
  spec: "auth-layer",
  task: "choose-auth-provider",
  decision_text: "Use Supabase Auth with PKCE flow",
  rationale: "Supabase is already our database provider, PKCE is more secure for SPAs than implicit flow, and it simplifies the deployment since we avoid a separate auth service."
})

list_decisions

List all recorded decisions across the project with rationale and context.

Parameters: none (uses active project)

Example:

list_decisions()

share_spec

Create a shareable public URL for a spec.

Parameters:

Name	Type	Description
`spec_name`	string	Name of the spec to share

Example:

share_spec({ spec_name: "auth-layer" })

unshare_spec

Revoke a shared spec link by its share token.

Parameters:

Name	Type	Description
`share_token`	string	The share token to revoke

Example:

unshare_spec({ share_token: "abc123def456" })

list_shares

List active shared spec links for the current project.

Parameters: none (uses active project)

Example:

list_shares()

get_briefing

Get a daily briefing summarizing the project state: decisions needed, human tasks ready, stale blocked tasks, code-ready tasks, and blocked count.

Parameters: none (uses active project)

Example:

get_briefing()

search

Full-text search across spec content, task content, and findings. Returns ranked results with matched snippets.

Parameters:

Name	Type	Description
`query`	string	Search query
`filter`	`"specs_only"` \| `"tasks_only"` \| `"findings_only"` (optional)	Limit search to a type

Example:

search({ query: "token refresh" })
search({ query: "Safari mobile", filter: "findings_only" })

workflow_guide

Get the complete Jig workflow guide as a refresher. Covers the full development lifecycle, file structure, task format, and best practices.

Parameters: none

Example:

workflow_guide()

MCP Reference

Table of contents

list_projects

switch_project

create_project

delete_project

list_specs

show_spec

create_spec

update_spec

reparent_spec

archive_spec

delete_spec

list_tasks

show_task

create_task

update_task

delete_task

move_task

verify_task

add_criterion

list_criteria

remove_criterion

list_runs

show_run

decompose

next_tasks

plan_parallel

show_status

show_tree

list_bundles

show_bundle

create_bundle

update_bundle

delete_bundle

list_snippets

show_snippet

create_snippet

delete_snippet

create_request

list_requests

show_request

link_to_request

resolve_request

search_requests

file_bug

file_idea

list_findings

dismiss_finding

add_attachment

list_attachments

record_decision

list_decisions

share_spec

unshare_spec

list_shares

get_briefing

search

workflow_guide