English | Русский

TAUSIK MCP — Tool Reference

147 tools for AI agents (current actual count, asserted via len(TOOLS)). The MCP surface covers everything an agent does day-to-day. A few CLI-only commands have no MCP equivalent — they are operator / maintenance verbs that don't belong in an agent loop: skill rebuild, skill bundle, fts optimize, db prune, audit vendors/research, config set/show, push-ok, run, doc extract/constants, hud, suggest-model, hygiene archive --confirm. For the agent's working set, prefer MCP tools over shell calls — they are atomic, return structured data, and keep your context cleaner.

Optional codebase-rag server adds 7 tools (search_code, find_symbol, …). It is enabled separately during bootstrap and is NOT part of the main 152 count - total with it is 154 tools.

Two MCP servers live in this project:

• tausik-project — project-scoped tools (147): tasks, sessions, knowledge, stacks, roles, gates, skills, exploration, audit, doctor, verify, usage logging.

There is also an optional codebase-rag server documented at the bottom.

Verify-First Contract (v1.5)

Heavy quality gates (pytest, tsc, cargo, phpstan, javac, js-test, terraform-validate, helm-lint, kubeconform, hadolint, ansible-lint) live on a dedicated verify trigger. The MCP workflow:

tausik_task_start(slug=…, package=true) # QG-0 + bounded context in one result
… work on code …
tausik_verify(task_slug=…)        # heavy: subprocess gates → caches green
tausik_task_done(slug=…, ac_verified=True)   # lightweight: cache lookup

tausik_task_done will refuse to close the task if the verify cache is missing or stale — it returns a structured failure with explicit remediation. Opt-out for CI: set {"task_done": {"auto_verify": true}} in .tausik/config.json so the heavy gates fire inside task_done like in pre-v1.5 releases.

Terminology: Verify / QG glossary distinguishes supported opt-out, QG bypass (not available for task_done), verify-cache bypass, and the pytest test shim.

Status, Health, Metrics

Tool	Description	Required Parameters
tausik_health	Health check: version, DB, tables	—
tausik_self_check	MCP-server freshness: startup time, watched-module mtime snapshot vs current on-disk mtimes, drift_detected flag, stale modules with delta_seconds, sibling MCP project server count. Call from /start to catch silent-hang precursors (gotchas #77/#79/#80).	—
tausik_status	Project overview: tasks, session, epics. Optional compact: true → one-line JSON (default text unchanged).	compact (optional)
tausik_doctor	4-group health (venv + DB + MCP + skills + drift)	—
tausik_metrics	SENAR metrics, or compact native usage with host=codex|kilo	host?
tausik_usage_event_log	Append manual row to usage_events (does not update session aggregates)	tokens_input, tokens_output, tokens_total, cost_usd
tausik_search	Full-text search across tasks, memory, decisions	query

Tasks

Tool	Description	Required Parameters
tausik_task_add	Create task (optionally in a story)	slug, title
tausik_task_quick	Quick creation with auto-slug	title
tausik_task_start	Start work; optionally return bounded context in the same result	slug, optional package
tausik_task_done	Complete (QG-2: ac_verified=true, scoped pytest, verify cache). Returns structured JSON: blocking_failures, per-gate results, cache status.	slug
tausik_task_show	Full task information, or bounded context with mode=package	slug; optional mode
tausik_task_list	List tasks with filters (status enum: planning,active,blocked,review,done)	—
tausik_task_update	Update fields (title/goal/AC/scope/notes/stack/complexity/role/tier/call_budget)	slug
tausik_task_plan	Set plan steps	slug, steps[]
tausik_task_step	Mark step as completed	slug, step_num
tausik_task_log	Append journal entry	slug, message
tausik_task_logs	Read structured logs (filter by phase)	slug
tausik_reason_step	RENAR reasoning step (intent|premise|action|verification)	slug, kind, content
tausik_task_replay	Chronological task timeline (logs + reasoning + events + verification)	slug
tausik_task_block	Block task	slug
tausik_task_unblock	Unblock	slug
tausik_task_review	Move to review	slug
tausik_task_delete	Delete task	slug
tausik_task_move	Move to another story	slug, new_story_slug
tausik_task_next	Pick next task by score	—
tausik_task_claim	Claim task (multi-agent)	slug, agent_id
tausik_task_unclaim	Release task	slug

tausik_task_done parameters

• ac_verified — required for QG-2
• evidence — inline AC verification log (replaces a separate task_log call)
• no_knowledge — confirm no knowledge to capture (suppresses warning)
• relevant_files[] — files modified; drives scoped pytest gate (basename match → tests/test_<file>.py). Empty list with non-empty original → gate skipped (no false-positive on full suite). Verify cache (10 min TTL) skips re-runs with same files_hash.

There is no --force on task_done — QG-2 cannot be bypassed. task_start does have --force to bypass session capacity, with audit trail.

tausik_task_done structured response

tausik_task_done returns JSON for agent workflows:

• stage flags (plan_complete, ac_verified, gates_passed)
• per-gate results (gates[])
• blocking_failures[] with gate, files, output, and remediation hints
• warnings[], cache_status, and final ok

Pre-1.4 there was a parallel tausik_task_done_v2 alias for the structured-JSON variant. v14b-task-done-rename-drop-v2 consolidated both into the single tausik_task_done returning the structured JSON above — there is no _v2 suffix. The Verify-First Contract is honoured on every path.

Sessions

Tool	Description	Required Parameters
tausik_session_start	Start session	—
tausik_session_end	End session	—
tausik_session_extend	Raise the active-time advisory threshold (advice, not a gate)	—
tausik_session_current	Current active session	—
tausik_session_list	List sessions	—
tausik_session_handoff	Save handoff data	handoff (object)
tausik_session_last_handoff	The live handoff, or session session_id's	session_id (opt.)
tausik_session_open (v1.5)	Compound RPC: host-context policy + session start + status + handoff + active/blocked tasks + self_check in one envelope. Powers /start Phase 1. host_context reports same-thread reopen state, native usage availability, advisory/hard pressure and the fresh-window prompt. Session and self_check are projected; large handoffs use a 4096-byte UTF-8 summary with explicit omissions and a full-recovery call. If _projection.requires_full_handoff is true, read the full handoff before resuming work. The bound applies to the handoff section, not the whole envelope. Full telemetry: tausik_self_check; full handoff: tausik_session_last_handoff.	—

Session time is gap-based active time (paused after 10-min idle gap), not wall clock, and it is advice, never a refusal (1.10). See session-active-time.md.

Hierarchy (Epics and Stories)

Tool	Description	Required Parameters
tausik_epic_add	Create epic	slug, title
tausik_epic_list	List epics; (stale: N) — tasks created since the description was last edited (a report, not a gate)	—
tausik_epic_update	Change an epic's title and/or description — the group's intent; at least one field	slug
tausik_epic_done	Complete epic	slug
tausik_epic_delete	Delete (cascade: stories + tasks)	slug
tausik_story_add	Create story in epic	epic_slug, slug, title
tausik_story_list	List stories; (stale: N) as for epics	—
tausik_story_update	Change a story's title and/or description; at least one field	slug
tausik_story_done	Complete story	slug
tausik_story_delete	Delete (cascade: tasks)	slug
tausik_roadmap	Tree: epic → story → task	—

RENAR substrate — SPEC + ADAPT (17 tools)

The RENAR substrate: formal requirements (SPEC) and requirement interpretation (ADAPT, §7) with forward interpretations, backward findings and the architect's signature (§7.5). Used by QG-0 for substantial/deep tasks and by tausik renar export / conformance. See also tausik_reason_step (RENAR trace) under "Tasks".

SPEC (8)

Tool	Description	Required Parameters
tausik_spec_add	Create a SPEC artifact. type is a closed list (ARCH/API/DATA/INT/PROC/UI/AI/SEC/OPS/TEST/DOC/UC; UC needs a body with role and a statement ref on every step); a new type is an amendment to the standard, not free text	slug, type, title, version
tausik_spec_list	List SPECs, optionally filtered by type (JSON)	—
tausik_spec_show	SPEC + linked tasks (JSON)	slug
tausik_spec_update	Patch mutable fields (title/version/content_ref/status); type and slug are immutable	slug
tausik_spec_delete	Delete a SPEC (cascade: task links)	slug
tausik_spec_link	Link a task to a SPEC (both must exist — no silent dangling links)	task_slug, spec_slug
tausik_spec_unlink	Unlink task ↔ SPEC	task_slug, spec_slug
tausik_spec_search	FTS5 over slug/title/content_ref (JSON)	query

ADAPT (9)

Tool	Description	Required Parameters
tausik_adapt_create	Create an ADAPT header (§7); tz_ref (the source requirement doc) is mandatory; starts in draft	slug, title, tz_ref
tausik_adapt_interpret	Forward interpretation (§7.4.3); tz_ref/citation/interpretation/scope_in/scope_out all required	tz_ref, citation, interpretation, scope_in, scope_out (+ adapt)
tausik_adapt_finding	Backward finding; category is a closed list of 7 (contradiction/gap/hidden-assumption/feasibility/regulatory/terminology/scope)	adapt_slug, category, description
tausik_adapt_sign	Architect signature (§7.5): signs the body with the project's ed25519 key ⇒ approved (§13.3.3 p.77 — status and signature are separate facts). role=client is REFUSED — ADR-011 withdrew the client signature under ADAPT; what the client approves belongs in an ACTZ	adapt_slug, role, signed_by
tausik_adapt_show	ADAPT + forward interpretations, findings, signatures, links (JSON)	slug
tausik_adapt_list	List ADAPTs, optionally filtered by status (§7.8.1 closed list: draft/review/asked/answered/approved/frozen/superseded)	—
tausik_adapt_delta	Delta-ADAPT superseding its parent (§7.6); the parent becomes superseded, and a later link to it is a FATAL dangling link (§7.6.4)	parent_slug, new_slug, title, tz_ref
tausik_adapt_link	Link an ADAPT to a task/SPEC; the target must exist; a link to a superseded ADAPT is FATAL (§7.6.4)	adapt_slug, target_type, target_slug
tausik_adapt_search	FTS5 over slug/title/tz_ref (JSON)	query

ACTZ (15)

The contractual clarification protocol (§5A, ADR-011) — client-facing, unlike ADAPT: what the client approves belongs here. Lifecycle draft → sent → signed → superseded, computed from signature-role coverage. One project ed25519 key exists (not one per party): architect signs for real; client records signed_by+signed_at only, no simulated independent signature. final_tz/orphans (§5A.4) are read-only projections over the signed points below — the derived acceptance reference, never a third copy of the text.

Tool	Description	Required Parameters
tausik_actz_create	Create an ACTZ header (§5A); tz_ref mandatory; starts in draft	slug, title, tz_ref
tausik_actz_point	Add a numbered point; only while draft (frozen once any signature is recorded). tz_ref names which clause of the original ТЗ (or a prior ACTZ point) this point clarifies	actz_slug, point_no, tz_ref, text
tausik_actz_sign	Record a signature (§5.5.3): architect signs the canonical body with the project ed25519 key; client records signed_by+signed_at only. First signature ⇒ sent; both roles ⇒ signed	actz_slug, role, signed_by
tausik_actz_verify	Verify the architect ed25519 signature against the current body	slug
tausik_actz_show	ACTZ + points, signatures, links (JSON)	slug
tausik_actz_list	List ACTZ headers, optionally filtered by status (draft/sent/signed/superseded)	—
tausik_actz_delta	Delta-ACTZ superseding its parent; the parent becomes superseded, a later link to it is refused	parent_slug, new_slug, title, tz_ref, supersession_rationale
tausik_actz_link	Link an ACTZ to a task/SPEC; target must exist; a link to a superseded ACTZ is refused	actz_slug, target_type, target_slug
tausik_actz_unlink	Remove an ACTZ↔task/SPEC link	actz_slug, target_type, target_slug
tausik_actz_delete	Delete an ACTZ (cascades points/signatures/links/decided-in edges)	slug
tausik_actz_search	FTS5 over slug/title/tz_ref (JSON)	query
tausik_actz_decided_in	Record that an ADAPT backward finding was decided-in a point of a SIGNED ACTZ, with provenance (linked_by); refuses an unsigned target	adapt_slug, finding_id, actz_slug, actz_point_no, linked_by
tausik_actz_decided_in_remove	Remove a decided-in edge	adapt_slug, finding_id, actz_slug, actz_point_no
tausik_actz_final_tz	The derived acceptance reference (§5A.4): per ТЗ clause, the latest both-role-signed point, naming what it overrode. as_of (ISO-8601) shows it at a past moment	—
tausik_actz_orphans	Signed points no ADAPT reflects — an obligation outside requirements (§5A.4, fatal), found by query	—

AT (9)

Acceptance Test artifacts (§8A, ADR-012) — the one check traceability (TC → SR → ADAPT → ТЗ) structurally cannot provide, because a wrong interpretation makes every TC pass. These tools RECORD the result of the isolated-generation procedure (docs/en/at-generation-procedure.md) — none of them generate anything. tz_text (verbatim contract quote) and generated_by are mandatory on create; check_freshness compares against the LIVE final_tz_snapshot for each AT's tz_ref and names what changed (§8A property 2 — regenerate before every trial). See also the at_freshness warn gate.

record_result/diagnose/release_readiness implement §8A.4/§10.4.3's routing matrix. TAUSIK has no first-class TC artifact yet (a separate, open task) — diagnose never reads pytest/verification_runs itself; the caller supplies tc_outcome explicitly. release_readiness needs no TC at all: it is ready only when every AT's latest outcome is green and fresh — distinct from QG-4, which is optional and measures business outcome.

Tool	Description	Required Parameters
tausik_at_create	Record an AT — the result of the isolated-generation procedure, not a generator	slug, tz_ref, tz_text, scenario, source_as_of, generated_by
tausik_at_show	Show an AT record (JSON)	slug
tausik_at_list	List AT records, optionally filtered by tz_ref (JSON)	—
tausik_at_delete	Delete an AT record	slug
tausik_at_search	FTS5 over slug/tz_ref/tz_text/scenario (JSON)	query
tausik_at_check_freshness	Which AT records are stale against the current final-TZ (§8A.2); omit slug to check all	—
tausik_at_record_result	Record one observed trial outcome (append-only — a re-run is a new row)	slug, outcome
tausik_at_diagnose	Route an AT's latest outcome against a caller-supplied tc_outcome (§8A.4/§10.4.3)	slug, tc_outcome
tausik_at_release_readiness	§8A.4 release gate: ready only when every AT is green and fresh	—

Knowledge

Tool	Description	Required Parameters
tausik_memory_add	Save to project memory; provenance observed / inferred (default) / told	type, title, content
tausik_memory_search	Full-text search in memory	query
tausik_memory_list	List entries (filter by type)	—
tausik_memory_show	Show entry by ID	id
tausik_memory_delete	Delete entry	id
tausik_memory_block	Compact markdown: recent decisions + conventions + dead ends (for /start re-injection)	—
tausik_memory_compact	Aggregate recent task_logs (phases + top words + top files)	—
tausik_memory_archive (v1.5)	Soft-archive memory rows older than a duration (90d / 12w / 2m / 1y). Dry-run unless confirm: true.	before (string), confirm (bool, optional)
tausik_memory_dedupe (v1.5)	List near-duplicate memory pairs above a similarity threshold (read-only).	threshold (float, optional), limit (int, optional)
tausik_decide	Record a decision; optional rejected (list of "option :: why") and supersedes (id, reason in rationale)	decision
tausik_decisions_list	List decisions	—

Memory types: pattern, gotcha, convention, context, dead_end.

Graph Memory

Tool	Description	Required Parameters
tausik_memory_link	Create edge between nodes	source_type, source_id, target_type, target_id, relation
tausik_memory_unlink	Soft-invalidate edge (never deletes)	edge_id
tausik_memory_related	Find related nodes (1–3 hops)	node_type, node_id
tausik_memory_graph	List edges with filters	—

Relation types: supersedes, caused_by, relates_to, contradicts.

Dead Ends and Explorations

Tool	Description	Required Parameters
tausik_dead_end	Document a failed approach	approach, reason
tausik_explore_start	Start time-boxed investigation	title
tausik_explore_end	End investigation	—
tausik_explore_current	Current investigation	—

Quality Gates and Verification

Tool	Description	Required Parameters
tausik_gates_status	Status of all gates (by stack)	—
tausik_gates_enable	Enable gate	name
tausik_gates_disable	Disable gate	name
tausik_verify	v1.5 Verify-First: run heavy gates (pytest, tsc, …) and cache green in verification_runs. After that tausik_task_done reads the cache and closes instantly.	task_slug

Available gates: pytest, ruff, mypy, bandit, tsc, eslint, go-vet, golangci-lint, cargo-check, clippy, phpstan, phpcs, javac, ktlint, filesize, class_surface, tdd_order. Stack-scoped gates auto-enable based on detected stack; universal gates (filesize, class_surface, tdd_order) apply to all stacks. class_surface is repo-wide rather than scoped: it caps a class's composed public surface after inheritance, which a per-file line cap cannot see.

tdd_order is disabled by default. Enable with tausik_gates_enable name=tdd_order.

Stacks

Tool	Description	Required Parameters
tausik_stack_list	List built-in + custom stacks	—
tausik_stack_show	Resolved stack: gates per language + override info	stack
tausik_stack_export	Export resolved declaration as JSON	stack
tausik_stack_diff	Diff between built-in and user override	stack
tausik_stack_reset	Remove user override at .tausik/stacks/<stack>/	stack
tausik_stack_lint	Validate user-override stack.json files	—
tausik_stack_scaffold	Create .tausik/stacks/<name>/{stack.json,guide.md} skeleton	name

DEFAULT_STACKS: 25 entries (python, fastapi, django, flask, react, next, vue, nuxt, svelte, typescript, javascript, go, rust, java, kotlin, swift, flutter, laravel, php, blade, ansible, terraform, helm, kubernetes, docker). Custom stacks via .tausik/config.json → custom_stacks.

Roles

Tool	Description	Required Parameters
tausik_role_list	List roles	—
tausik_role_show	Show role profile	slug
tausik_role_create	Create role (optionally extends a base profile)	slug, title
tausik_role_update	Update role metadata	slug
tausik_role_delete	Delete role	slug
tausik_role_seed	Bootstrap rows from harness/roles/*.md + existing task usage	—

Role storage is hybrid: SQLite metadata + harness/roles/{role}.md profile markdown. Roles on tasks remain free-text.

Periodic Audit (SENAR Rule 9.5)

Tool	Description	Required Parameters
tausik_audit_check	Check whether audit is overdue	—
tausik_audit_mark	Mark audit as completed	—

Skills

Tool	Description	Required Parameters
tausik_skill_list	List skills: active, vendored, available	—
tausik_skill_install	Install skill from repo (clone + copy + deps)	name
tausik_skill_uninstall	Uninstall skill completely	name
tausik_skill_activate	Activate installed skill	name
tausik_skill_deactivate	Deactivate skill (keep files)	name
tausik_skill_repo_add	Add TAUSIK-compatible skill repo (third-party URLs need force)	url, optional force
tausik_skill_repo_remove	Remove skill repo	name
tausik_skill_repo_list	List repos and available skills	—
tausik_skill_catalog	Discovery: list skills offered by configured/cloned repos (name, category, description)	optional repo, optional as_json

Cross-Project Queue (CQ)

Tool	Description	Required Parameters
tausik_cq_publish	Publish a cross-project event	payload
tausik_cq_query	Query cross-project queue	—

Multi-agent and Maintenance

Tool	Description	Required Parameters
tausik_team	Tasks grouped by agent	—
tausik_events	Audit log (events)	—
tausik_update_claudemd	Update dynamic section in CLAUDE.md	—
tausik_fts_optimize	Optimize FTS5 indexes	—

Codebase RAG (separate optional MCP server)

Tool	Description	Required Parameters
search_code	Search project code via RAG index	query
search_knowledge	Search project knowledge base	query
reindex	Reindex the codebase	mode (incremental/full), max_seconds (soft limit, full only). v1.5: stderr progress every 100 files; truncated=true on timeout.
rag_status	RAG index status	—
archive_done	Archive completed tasks	—
cache_web_result	Cache web search result for reuse	query, content
search_web_cache	Search cached web results	query

These are not part of the main 147 count — they belong to the optional codebase-rag server.

Scoped tool surface (mcp.scope_tools_exposure)

Off by default. When you set mcp.scope_tools_exposure: true in config.json, the server narrows the advertised tool-list to what the active task is allowed to use: the union of the task's declared scope_tools (SENAR Rule 2 ACL) and an always-safe core — the whole tausik_task_* and tausik_session_* families plus tausik_status, tausik_verify, tausik_doctor, tausik_self_check, tausik_update_claudemd and the *_search tools. Every other tool is hidden from the list, cutting both the token cost of the tool definitions and the attack surface.

It is fail-open: all tools are exposed whenever no task is active, no active task declared a non-empty scope_tools, or the scope cannot be resolved — so turning it on never strands a project that never declared a scope. Hiding is a UX/token optimization, not the security barrier: a hidden tool called directly still passes the existing scope enforcement, and the write-gate is untouched. The scoped list is recomputed each time the host fetches list_tools — i.e. on every server connect with a task already active.

Measured cost. The full authored surface is 147 tools ≈ 62 KB of tool definitions (~15.9k estimated tokens; tests/test_mcp_tool_token_cost.py pins this and ratchets it). Under Claude Code deferred loading (ENABLE_TOOL_SEARCH) only tool names load eagerly and each description is truncated to 2 KB — a ratchet test keeps every TAUSIK description under that limit so none is silently cut, and asserts names stay unique and searchable so name-based dispatch still resolves.

Launching the Tausik MCP Server

The bootstrap step generates IDE-specific MCP launchers under harness/<ide>/mcp/. Claude Code reads .claude/settings.json (auto-generated). To regenerate IDE assets and MCP wiring, run python bootstrap/bootstrap.py from your TAUSIK checkout (or python .tausik-lib/bootstrap/bootstrap.py when using the submodule layout). Use python bootstrap/bootstrap.py --refresh only to rewrite .tausik/config.json (e.g. after setting TAUSIK_MODEL_PROFILE) without copying skills/scripts — it does not regenerate .mcp.json files.

Context economy: schemas on demand

mcp.compact_tool_list in .tausik/config.json is enabled by bootstrap unless the project explicitly sets it to false. Without generated config, the server fails open to the full list. When on, full schemas stay with a 23-tool core; the other 124 appear as a name and the first 60 characters of their description. Any of those schemas is one call away: tausik_tool_schema(name=...), with query matching a substring and an empty argument returning the name list.

Measured on a fresh 147-tool stdio surface on 2026-10-02, the minified UTF-8 list drops from 54,566 to 33,752 bytes (-38.1%). The 60-character cut is also a measurement rather than a preference: name-only is smaller, but removes the cue an agent uses to decide whose schema to ask for and can spend the saving on an extra turn. The complete project-controlled inventory is in context-economy.md.

Set the flag to false to opt out after checking turns-per-task in your own logs. Missing, malformed or unreadable config always returns the full list.