MCP Tool Reference

The Vibeless MCP server exposes the tools below to your coding agent. All of them execute locally against your project's database and code graph — none make external LLM calls, and none consume credits. Workspace tools appear only when the project belongs to a workspace.

Authentication

You never manage credentials for these tools by hand. For Claude Code, Codex, and Cursor the one-click installer writes an HTTP MCP entry whose Authorization: Bearer header carries the project's auto-generated token; the token authenticates every call and scopes it to that one project. Manual (Generic MCP) setups pass the same token as the single VIBELESS_PROJECT_TOKEN environment variable. Rotating the token in Connected Agents invalidates old configs — reinstall from the same pane.

Conventions

• Results are returned as MCP text content — formatted Markdown for context-shaped tools, JSON for data-shaped tools. The output fields listed below describe those JSON payloads; exact shapes can grow between releases.
• Errors come back as MCP tool errors with a message (for example node_not_found, a rejected token, or "Vibeless app is not running" when the desktop app is closed — calls recover automatically once you reopen it).
• "Data only" tools return facts and let your agent do the reasoning. Vibeless does not run its own model to judge compliance — constraint and decision tools hand the agent everything it needs to decide.

Start here: navigation tools

vibeless_declare_intent

Tell Vibeless what the agent is working on. Returns the full project map plus ranked starting points — the intended first call of every session.

| Input | Type | Required | Description | |---|---|---|---| | description | string | yes | Natural-language description of what the agent is working on |

Returns: scope (extracted scope label), project_map (every active spec node with name, kind, summary, and approximate token cost), suggested_starts (up to 5 ranked node references — guesses; the map is authoritative), and next (guidance for going deeper).

vibeless_get_node

Unified per-node fetcher across both graphs. Dispatches by ID: code-topology nodes and spec (context) nodes. Returns exactly one node and its content — never a bundle.

| Input | Type | Required | Description | |---|---|---|---| | id | string | yes | Node ID (topology content hash or spec ContextNode UUID) | | sections | string[] | no | Spec nodes: return only these section_ids from a prior outline. Mutually exclusive with full | | full | boolean | no | Spec nodes: force complete content instead of the outline default | | chunk | number | no | Spec nodes: 0-based chunk index for large heading-less content |

Returns: { graph: "code", node: … } or { graph: "spec", node: … }. Spec nodes over 8KB default to outline mode: content is replaced by an outline (heading/section-id list) plus a capped preamble, with truncated: true — fetch the sections you need next. Heading-less large nodes page via chunk, with chunk_count in the response. Unknown IDs throw node_not_found.

vibeless_spec_neighbors

A spec node's stored graph edges plus a computed governs block — the code-topology nodes and repository files this spec/constraint governs, matched live by its file globs. No node content is returned; walk into a governed node with vibeless_get_node.

| Input | Type | Required | Description | |---|---|---|---| | node_id | string | yes | Spec graph ContextNode ID |

vibeless_search_specs

Full-text search across all indexed project specifications (BM25-ranked).

| Input | Type | Required | Description | |---|---|---|---| | query | string | yes | Search query string |

Returns: results (entity type, id, name, matching content) and query. Capped at 20 rows by relevance — refine the query rather than paginating.

Project context

vibeless_get_project_context

Project info, current phase, constraints, hooks, the active ticket, and enforcement coverage — the broad orientation call. Includes an architecture summary when one exists (fetch the full document with vibeless_get_architecture). No inputs.

vibeless_get_architecture

The full project architecture document as Markdown. No inputs.

vibeless_get_phase_spec

Phase specification with tasks and boundaries.

| Input | Type | Required | Description | |---|---|---|---| | phase_id | string | yes | Phase ID, or "current" for the active phase |

vibeless_get_task_spec

A single task's specification with its constraints merged from phase and project level.

| Input | Type | Required | Description | |---|---|---|---| | task_id | string | yes | Task ID |

vibeless_get_adapter_info

The active adapter configuration for the project. No inputs.

Tasks & tickets

vibeless_list_open_tasks

Everything still actionable: status backlog, pending, in_progress, review, or blocked — everything except done/skipped.

| Input | Type | Required | Description | |---|---|---|---| | phase_id | string | no | Limit to one phase |

Returns: open_tasks (each with id, phase, name, status, spec, acceptance criteria) and total.

vibeless_create_task

Creates a new task in a phase. Agent-created tasks always land at the bottom of Backlog, and tasks are permanent records — agents can create and move them, never edit or delete them. Record progress with vibeless_add_task_comment.

| Input | Type | Required | Description | |---|---|---|---| | phase_id | string | yes | Phase the task belongs to | | name | string | yes | Short task name (max 255 characters) | | spec | string | no | What the task is — the permanent spec text (max 50,000 characters) | | acceptance_criteria | string | no | How completion will be judged (max 50,000 characters) |

Returns: task_id, name, status, and task_order.

vibeless_update_task_status

Updates a task and hands the agent its next unit of work in the same call.

| Input | Type | Required | Description | |---|---|---|---| | task_id | string | yes | Task ID to update | | status | enum | yes | backlog | pending | in_progress | review | done (legacy blocked/complete/skipped accepted and normalized) | | notes | string | no | Echoed back in the result; not persisted to the task |

Returns: updated_task, next_task (first pending task in the phase, falling back to backlog, or null), and notes. When post-task reports are enabled, moving a task to review requires filing a certificate via vibeless_attach_report first.

vibeless_get_active_ticket / vibeless_set_active_ticket

Read or pin the ticket the agent is working. get takes no inputs and returns the full task spec with merged constraints; set takes task_id (string, required) and returns the previously active task id (or null).

vibeless_add_task_comment

Appends a permanent comment to a task's work-narrative thread — "what was done and how" as work progresses. Comments can never be edited or deleted; the formal review artifact remains vibeless_attach_report.

| Input | Type | Required | Description | |---|---|---|---| | task_id | string | yes | Task to comment on | | body | string | yes | Comment text (max 10,000 characters) | | agent_session_hint | string | no | Identifies the agent session |

Returns: comment_id and created_at.

vibeless_attach_report

Files a semi-formal completion certificate for a task — used with the post-task report hook.

| Input | Type | Required | Description | |---|---|---|---| | task_id | string | yes | Task to attach the report to | | certificate | object | yes | definitions, premises, analysis, counterexample, formal_conclusion (all required strings), optional edge_cases, and answer: YES | NO | PARTIAL | | agent_session_hint | string | no | Identifies the agent session that produced the report |

Decisions & constraints

vibeless_check_constraint

Constraints, related prior decisions (relevance-ranked), and rule context for a proposed action. Data only — your agent decides compliance.

| Input | Type | Required | Description | |---|---|---|---| | proposed_action | string | yes | The proposed action to check |

vibeless_list_constraints

The project's constraints array, read-only. No inputs.

vibeless_log_decision

Persists a decision and returns it alongside potentially-overlapping prior decisions for the agent to review.

| Input | Type | Required | Description | |---|---|---|---| | decision | string | yes | The decision made | | rationale | string | yes | Reason for the decision | | alternatives | string | yes | Alternatives considered | | task_id | string | no | Associated task |

Returns: the stored decision record plus keyword_conflicts — prior decisions that may overlap.

vibeless_list_decisions

Decision log, newest first.

| Input | Type | Required | Description | |---|---|---|---| | limit | number | no | Max items (default 50, max 200) |

Drift & history

vibeless_run_drift_check

Runs the deterministic drift engine server-side (in the app — still no LLM, no credits) and returns the persisted report: report id, entries filtered to the project's drift threshold, diagnostics, and an enforceability coverage summary. Avoid calling in a tight loop. No inputs.

vibeless_get_version_history

Recent version-history events for an entity.

| Input | Type | Required | Description | |---|---|---|---| | entity_type | string | yes | project, phase, task, … | | entity_id | string | yes | Entity ID | | limit | number | no | Max events to return |

vibeless_get_hooks

Active hooks for a trigger event, sorted by priority.

| Input | Type | Required | Description | |---|---|---|---| | trigger_event | string | yes | Canonical event (session_start, user_prompt_submit, pre_tool_use, post_tool_use, stop, pre_compact, pre_shell_execution); PascalCase native names are normalized |

Code topology

vibeless_topology_summary

Zero-argument overview of the code graph: node/edge counts by kind and extractor, the ten most-connected nodes, and last extraction-run metadata.

vibeless_topology_query

Filters the code graph, or walks a node's edges.

| Input | Type | Required | Description | |---|---|---|---| | kinds | string[] | no | Filter by node kind, e.g. ["route","handler"] | | name_contains | string | no | Case-insensitive substring on node name | | source_file_contains | string | no | Case-insensitive substring on source file path | | neighbors_of | string | no | Node id — returns that node plus inbound/outbound edges; other filters ignored | | limit | number | no | Max nodes in filter mode (default 50, max 200) |

At least one of kinds, name_contains, source_file_contains, or neighbors_of is required.

Workspace tools

Available only when the project belongs to a workspace.

vibeless_get_workspace_context

Workspace-level context nodes, member projects, and link relationships. No inputs.

vibeless_get_linked_project_context

Context from a linked project, scoped by the link's coupling level.

| Input | Type | Required | Description | |---|---|---|---| | target_project_id | string | yes | Linked project to fetch context from |

vibeless_create_project

Creates a project in the current workspace. Respects your plan's active-project limit — at the cap it returns an agent-actionable error instead of failing silently.

| Input | Type | Required | Description | |---|---|---|---| | name | string | yes | Project name | | goal_statement | string | yes | Project goal | | description | string | no | Project description | | tech_stack | string | no | Tech stack as a JSON string | | constraints | string | no | Constraints as a JSON array string | | non_goals | string | no | Non-goals as a JSON array string |

vibeless_link_projects

Links two projects with a coupling level.

| Input | Type | Required | Description | |---|---|---|---| | source_project_id | string | yes | Source project | | target_project_id | string | yes | Target project | | coupling_level | enum | yes | awareness | dependency | read | governance | | direction | enum | no | uni | bi (default bi) |

vibeless_check_cross_project_constraint

Like vibeless_check_constraint, but also returns workspace governance rules and shared governance nodes. Takes proposed_action (string, required).

Deprecated

vibeless_get_context

Returns pointer IDs only — never content. Superseded by vibeless_declare_intent + vibeless_get_node; kept temporarily for adapters mid-migration. Takes scope (string, required).

Worked example

A typical session opening — declare intent, then drill into what the map surfaced:

// → vibeless_declare_intent
{ "description": "Add rate limiting to the newsletter signup endpoint" }

// ← (abridged, illustrative)
{
  "scope": "newsletter rate limiting",
  "project_map": [
    { "id": "b41f…", "name": "API constraints", "kind": "constraint", "approx_tokens": 900 },
    { "id": "77c2…", "name": "Newsletter flow spec", "kind": "spec", "approx_tokens": 2400 }
  ],
  "suggested_starts": [{ "id": "77c2…", "name": "Newsletter flow spec" }],
  "next": "Skim the map; open nodes with vibeless_get_node…"
}

// → vibeless_get_node
{ "id": "77c2…" }

// ← large spec node: outline mode
{
  "graph": "spec",
  "node": {
    "name": "Newsletter flow spec",
    "outline": [
      { "section_id": "s1", "heading": "Consent capture" },
      { "section_id": "s2", "heading": "Rate limits" }
    ],
    "preamble": "…",
    "truncated": true
  }
}

// → vibeless_get_node
{ "id": "77c2…", "sections": ["s2"] }

Then check the ground rules before writing code:

// → vibeless_check_constraint
{ "proposed_action": "Introduce a Redis-backed rate limiter for /api/newsletter" }