ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
use std::collections::HashMap;
use std::path::PathBuf;
use std::process::Command;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use rmcp::{
handler::server::{router::tool::ToolRouter, wrapper::Parameters},
model::{ServerCapabilities, ServerInfo},
schemars, tool, tool_handler, tool_router, ServerHandler, ServiceExt,
};
use serde::{Deserialize, Serialize};
use super::board_watch::{BoardView, TaskMark};
use crate::agent::hook_status::{AgentHookStatus, HookState};
use crate::config::{GlobalConfig, ProjectConfig};
use crate::core::actions::CallerKind;
use crate::db::{Database, Task, TaskStatus, TransitionRequest};
/// Whether the MCP server is bound to a specific project or serves all projects globally.
#[derive(Debug, Clone)]
pub enum ServerMode {
/// Serve a single project (legacy / orchestrator mode β path is fixed at startup).
Project(PathBuf),
/// Serve all projects indexed in the global DB.
/// CRUD tools require a `project_id` parameter.
Global,
}
// === Parameter types ===
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct ListProjectsParams {}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct GetConfigParams {
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct ListTasksParams {
/// Filter by status: "backlog", "planning", "running", "review", "done". Omit for all tasks.
#[schemars(description = "Filter by status: backlog, planning, running, review, done")]
pub status: Option<String>,
/// Include each task's description. Off by default: a description is most
/// of a listing's bytes and a polling caller wrote them itself.
#[schemars(
description = "Include each task's full description (default false). get_task always includes it."
)]
pub include_description: Option<bool>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct WaitForBoardChangeParams {
/// How long to wait for something to need you before answering anyway.
#[schemars(
description = "Seconds to wait before answering anyway (default 300, max 900). A timeout is not an error: it means nothing needed you."
)]
pub timeout_secs: Option<u64>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct GetTaskParams {
/// The task ID (UUID)
#[schemars(description = "The task ID (UUID)")]
pub task_id: String,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct MoveTaskParams {
/// The task ID (UUID)
#[schemars(description = "The task ID (UUID)")]
pub task_id: String,
/// Action: "research", "move_forward", "move_to_planning", "move_to_running", "move_to_review", "move_to_done", "resume", "escalate_to_user"
#[schemars(
description = "Action: research (start research for backlog task), move_forward, move_to_planning, move_to_running, move_to_review, move_to_done, resume, escalate_to_user"
)]
pub action: String,
/// Optional reason (used with escalate_to_user action)
#[schemars(description = "Optional reason, used with escalate_to_user action")]
pub reason: Option<String>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct GetTransitionStatusParams {
/// The transition request ID returned by move_task
#[schemars(description = "The transition request ID returned by move_task")]
pub request_id: String,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct CheckConflictsParams {
/// Optional task ID. If omitted, checks all tasks in Review status.
#[schemars(description = "Optional task ID. If omitted, checks all tasks in Review status.")]
pub task_id: Option<String>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct GetNotificationsParams {
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct ReadPaneParams {
/// The task ID (UUID)
#[schemars(description = "The task ID (UUID)")]
pub task_id: String,
/// Number of lines to read from the end of the pane (default 50)
#[schemars(description = "Number of lines to read from the end of the pane (default 50)")]
pub lines: Option<i32>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct SendToTaskParams {
/// The task ID (UUID)
#[schemars(description = "The task ID (UUID)")]
pub task_id: String,
/// Message to send to the task's agent pane (followed by Enter). Max 4096 bytes, no null bytes.
#[schemars(
description = "Message to send to the task's agent pane (followed by Enter). Max 4096 bytes."
)]
pub message: String,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct CreateTaskParams {
/// Task title
#[schemars(description = "Task title")]
pub title: String,
/// Task description (what to implement, context, approach hints)
#[schemars(description = "Task description (what to implement, context, approach hints)")]
pub description: Option<String>,
/// Workflow plugin name (defaults to project's active plugin)
#[schemars(description = "Workflow plugin name (defaults to project's active plugin)")]
pub plugin: Option<String>,
/// Comma-separated task IDs that this task depends on
#[schemars(
description = "Comma-separated task IDs that this task depends on (must complete before this task starts)"
)]
pub referenced_tasks: Option<String>,
/// Base branch to create worktree from (defaults to project's main branch)
#[schemars(
description = "Base branch to create the worktree from (e.g. another task's branch for stacked PRs). Defaults to project's main branch."
)]
pub base_branch: Option<String>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct BatchTask {
/// Task title
#[schemars(description = "Task title")]
pub title: String,
/// Task description
#[schemars(description = "Task description (what to implement, context, approach hints)")]
pub description: Option<String>,
/// Workflow plugin name (defaults to project's active plugin)
#[schemars(description = "Workflow plugin name (defaults to project's active plugin)")]
pub plugin: Option<String>,
/// Indices (0-based) into the tasks array that this task depends on
#[schemars(
description = "Indices (0-based) into the tasks array that this task depends on. Referenced tasks must have a lower index (no forward references)."
)]
pub depends_on: Option<Vec<usize>>,
/// Base branch to create worktree from (defaults to project's main branch)
#[schemars(
description = "Base branch to create the worktree from (e.g. another task's branch for stacked PRs). Defaults to project's main branch."
)]
pub base_branch: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct CreateTasksBatchParams {
/// Array of tasks to create, with index-based dependency wiring
#[schemars(
description = "Array of tasks to create. Use depends_on with 0-based indices to wire dependencies between them."
)]
pub tasks: Vec<BatchTask>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct UpdateTaskParams {
/// The task ID (UUID) to update
#[schemars(description = "The task ID (UUID) to update. Only backlog tasks can be updated.")]
pub task_id: String,
/// New title (if provided)
#[schemars(description = "New task title")]
pub title: Option<String>,
/// New description (if provided)
#[schemars(description = "New task description")]
pub description: Option<String>,
/// New plugin (if provided)
#[schemars(description = "New workflow plugin name")]
pub plugin: Option<String>,
/// New referenced tasks (if provided, replaces existing)
#[schemars(
description = "Comma-separated task IDs that this task depends on (replaces existing dependencies)"
)]
pub referenced_tasks: Option<String>,
/// New base branch (if provided)
#[schemars(
description = "Base branch to create the worktree from (e.g. another task's branch for stacked PRs)"
)]
pub base_branch: Option<String>,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct DeleteTaskParams {
/// The task ID (UUID) to delete
#[schemars(description = "The task ID (UUID) to delete. Only backlog tasks can be deleted.")]
pub task_id: String,
/// Project ID (required in global mode β call list_projects first to get IDs).
#[schemars(
description = "Project ID. Required in global mode. Call list_projects first to get project IDs."
)]
pub project_id: Option<String>,
}
// === Response types ===
#[derive(Serialize)]
struct ProjectSummary {
id: String,
name: String,
path: String,
}
/// One card, as a polling caller sees it.
///
/// Every optional field is omitted when empty, and the description only on
/// request: this is the response a supervising session receives most, and it
/// re-reads each one on every later turn. Measured on a 14-task run,
/// descriptions were 80% of a listing's bytes β text the caller wrote itself
/// when it created the tasks.
#[derive(Serialize)]
struct TaskSummary {
id: String,
title: String,
#[serde(skip_serializing_if = "Option::is_none")]
description: Option<String>,
status: String,
agent: String,
#[serde(skip_serializing_if = "Option::is_none")]
branch_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pr_url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
plugin: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
referenced_tasks: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
base_branch: Option<String>,
/// Why the task was flagged for a person β a merge conflict, an
/// escalation. Present only when set.
#[serde(skip_serializing_if = "Option::is_none")]
escalation_note: Option<String>,
deps_satisfied: bool,
/// The TUI's published phase status, or `None` when nothing has been
/// observed for this task. Weigh it against `phase_age_secs` rather than
/// treating it as live β with no TUI running, nothing refreshes it.
#[serde(skip_serializing_if = "Option::is_none")]
phase_status: Option<String>,
/// How many seconds ago that status was observed. The refresh republishes
/// every live task on every pass, so a small age means "seen just now" and
/// a large one means nothing is watching this board β which is a different
/// problem from a task that is genuinely idle.
#[serde(skip_serializing_if = "Option::is_none")]
phase_age_secs: Option<i64>,
}
/// The settings that decide how a run behaves, already merged.
///
/// Only the fields a caller acts on. The theme is not here β nothing driving
/// the board makes a decision from it β and neither is anything secret.
#[derive(Serialize)]
struct EffectiveConfig {
/// Where these values came from, so a caller can say *which* file to edit
/// rather than guess at `~/.config/agtx/config.toml`.
global_config_path: String,
project_config_path: String,
project_config_exists: bool,
/// Whether agtx answers agents' trust and bypass-permission dialogs. When
/// false, an unattended run parks every task as `blocked` on its first
/// dialog with nobody to answer it. Global-only: a project config cannot
/// set this, because a repository must not be able to grant itself trust.
auto_trust: bool,
default_agent: String,
/// Per-phase overrides. A phase absent here uses `default_agent`.
phase_agents: serde_json::Value,
worktree_enabled: bool,
skip_worktree: bool,
auto_cleanup: bool,
/// Empty means auto-detect (main, then master).
base_branch: String,
worktree_dir: String,
branch_prefix: String,
workflow_plugin: Option<String>,
agent_hooks: bool,
github_url: Option<String>,
}
/// The board, plus the one fact that says whether any of it is live.
///
/// `tui_connected` belongs at board level rather than on each card: it is one
/// answer for the whole project, and repeating it per task would imply it could
/// differ between them. It is wrapped around the task list rather than offered
/// as a separate tool because a caller needs it on *every* poll β a separate
/// call is one a polling loop will skip, and skipping it means reading frozen
/// rows as live state.
#[derive(Serialize)]
struct BoardListing {
/// Whether a TUI has beaten recently. When false, nothing is executing
/// queued transitions and every `phase_status` below is frozen at whatever
/// was last observed β stale, not current.
tui_connected: bool,
tasks: Vec<TaskSummary>,
}
/// The answer to `wait_for_board_change`: only what differs from what this
/// session was last shown.
#[derive(Serialize)]
struct BoardChanges {
tui_connected: bool,
/// True when the wait ran out with nothing needing the caller. `tasks` can
/// still be non-empty β moves into states that ask nothing of it, such as
/// a task starting to work, are reported but do not wake a wait.
timed_out: bool,
tasks: Vec<TaskSummary>,
/// Ids of tasks this session was shown that no longer exist.
#[serde(skip_serializing_if = "Vec::is_empty")]
removed: Vec<String>,
/// Outcomes of `move_task` requests this session queued, since it was last
/// told. What makes polling `get_transition_status` unnecessary.
#[serde(skip_serializing_if = "Vec::is_empty")]
transitions: Vec<ResolvedTransition>,
}
#[derive(Debug, Serialize, Clone)]
struct ResolvedTransition {
request_id: String,
task_id: String,
action: String,
/// `completed` or `error`.
status: String,
#[serde(skip_serializing_if = "Option::is_none")]
error: Option<String>,
}
/// A `move_task` request this session queued and has not been told the
/// outcome of.
#[derive(Debug, Clone)]
struct QueuedMove {
request_id: String,
task_id: String,
action: String,
}
/// One MCP session's view of one board, for `wait_for_board_change`.
///
/// Kept in the server because the server *is* the session: each client spawns
/// its own `agtx mcp-serve` over stdio, so this map lives exactly as long as
/// the caller it describes.
#[derive(Debug, Default)]
struct SessionBoard {
view: BoardView,
queued: Vec<QueuedMove>,
/// Outcomes found by a poll but not yet returned to the caller.
resolved: Vec<ResolvedTransition>,
}
/// One pass of a wait, read and folded into the session's view.
struct BoardPoll {
snapshot: Vec<(TaskSummary, TaskMark)>,
tui_connected: bool,
wake: bool,
}
/// How long a wait lasts when the caller does not say.
const DEFAULT_WAIT_SECS: u64 = 300;
/// The longest wait a caller can ask for. A timeout is cheap β one turn β and
/// a cap keeps a stuck call from outliving a client's own tool-call limit.
const MAX_WAIT_SECS: u64 = 900;
/// How often a wait re-reads the board. The TUI refreshes phase status every
/// two seconds, so reading faster than this finds nothing new.
const WAIT_POLL_INTERVAL: Duration = Duration::from_secs(1);
#[derive(Serialize)]
struct TaskDetail {
id: String,
title: String,
description: Option<String>,
status: String,
agent: String,
project_id: String,
session_name: Option<String>,
worktree_path: Option<String>,
branch_name: Option<String>,
pr_number: Option<i32>,
pr_url: Option<String>,
plugin: Option<String>,
cycle: i32,
referenced_tasks: Option<String>,
base_branch: Option<String>,
escalation_note: Option<String>,
created_at: String,
updated_at: String,
/// Whether all referenced_tasks (dependencies) are in Review or Done.
deps_satisfied: bool,
/// Dependencies that are not yet in Review or Done status.
blocking_tasks: Vec<BlockingTask>,
/// Actions the orchestrator can take on this task given its current status and plugin rules.
allowed_actions: Vec<String>,
/// The agent's own report of what it is doing: "working", "blocked",
/// "waiting" or "ended". Absent when the agent reports nothing (hooks
/// disabled, or an agent that does not support them).
#[serde(skip_serializing_if = "Option::is_none")]
agent_state: Option<String>,
/// What the agent is waiting for, when `agent_state` is "blocked". This is
/// the permission prompt or question text the agent itself reported.
#[serde(skip_serializing_if = "Option::is_none")]
blocked_reason: Option<String>,
/// The TUI's own verdict on the phase: working, blocked, idle, ready or
/// exited. Distinct from `agent_state`, which is what the agent reports
/// about itself β this one also covers agents with no hooks, and is the
/// only signal that can say `ready` (the phase artifact exists) or
/// `exited` (the window is gone).
#[serde(skip_serializing_if = "Option::is_none")]
phase_status: Option<String>,
/// How many seconds ago `phase_status` was observed. See `TaskSummary`.
#[serde(skip_serializing_if = "Option::is_none")]
phase_age_secs: Option<i64>,
/// Whether a TUI is running for this project. When false, `phase_status` is
/// frozen rather than current, and no queued transition will execute.
tui_connected: bool,
}
#[derive(Serialize)]
struct BlockingTask {
id: String,
title: String,
status: String,
}
#[derive(Serialize)]
struct MoveTaskResult {
request_id: String,
message: String,
}
#[derive(Serialize)]
struct TransitionStatusResult {
request_id: String,
status: String,
error: Option<String>,
}
#[derive(Serialize)]
struct ConflictCheckResult {
task_id: String,
title: String,
branch_name: Option<String>,
has_conflicts: bool,
conflicting_files: Vec<String>,
error: Option<String>,
}
#[derive(Serialize)]
struct CheckConflictsResponse {
main_branch: String,
results: Vec<ConflictCheckResult>,
}
#[derive(Serialize)]
struct NotificationItem {
message: String,
created_at: String,
}
#[derive(Serialize)]
struct GetNotificationsResponse {
notifications: Vec<NotificationItem>,
}
#[derive(Serialize)]
struct ReadPaneResponse {
task_id: String,
session_name: String,
content: String,
lines_requested: i32,
}
#[derive(Serialize)]
struct SendToTaskResponse {
task_id: String,
session_name: String,
success: bool,
message: String,
}
#[derive(Serialize)]
struct CreateTaskResponse {
id: String,
title: String,
status: String,
}
#[derive(Serialize)]
struct BatchTaskResponse {
index: usize,
id: String,
title: String,
}
#[derive(Serialize)]
struct CreateTasksBatchResponse {
created: Vec<BatchTaskResponse>,
count: usize,
}
#[derive(Serialize)]
struct UpdateTaskResponse {
id: String,
title: String,
updated_fields: Vec<String>,
}
#[derive(Serialize)]
struct DeleteTaskResponse {
id: String,
title: String,
message: String,
}
/// How long a TUI heartbeat stays trusted. Three beats of the TUI's
/// `TRANSITION_POLL_INTERVAL`, so one missed tick is not read as a disconnect β
/// the same window the web API applies, since the two answer the same question.
const TUI_HEARTBEAT_STALE_AFTER: chrono::Duration = chrono::Duration::seconds(6);
// === MCP Server ===
#[derive(Debug, Clone)]
pub struct AgtxMcpServer {
mode: ServerMode,
/// When each project's `board_watch` row was last marked, so a read burst
/// costs one write rather than one per tool call. Shared across clones
/// because rmcp clones the server per request.
watched: Arc<Mutex<HashMap<String, Instant>>>,
/// What this session has been shown of each project's board, keyed by
/// project path. Shared across clones for the same reason as `watched`.
boards: Arc<Mutex<HashMap<String, SessionBoard>>>,
tool_router: ToolRouter<Self>,
}
impl AgtxMcpServer {
fn new(mode: ServerMode) -> Self {
Self {
mode,
watched: Arc::new(Mutex::new(HashMap::new())),
boards: Arc::new(Mutex::new(HashMap::new())),
tool_router: Self::tool_router(),
}
}
fn project_key(&self, project_id: Option<&str>) -> Result<String, String> {
self.resolve_project_path(project_id)
.map(|p| p.to_string_lossy().to_string())
}
/// Run `f` on this session's view of a project's board.
fn with_board<R>(&self, key: &str, f: impl FnOnce(&mut SessionBoard) -> R) -> R {
let mut boards = self.boards.lock().unwrap_or_else(|e| e.into_inner());
f(boards.entry(key.to_string()).or_default())
}
/// When the agent's hook last reported a turn boundary β see
/// [`TaskMark::turn_ts`].
fn turn_ts(hook: Option<&AgentHookStatus>) -> Option<i64> {
hook.filter(|h| h.state != HookState::Working).map(|h| h.ts)
}
/// Summaries of `tasks`, each with the mark a wait compares.
///
/// One runtime query for the whole board rather than one per task: this is
/// what a polling caller runs most, and the one that grows with the project.
fn board_snapshot(
db: &Database,
tasks: Vec<Task>,
include_description: bool,
) -> Vec<(TaskSummary, TaskMark)> {
let runtime = db.list_task_runtime().unwrap_or_default();
let now = chrono::Utc::now().timestamp();
tasks
.into_iter()
.map(|t| {
let deps_satisfied = db.deps_satisfied(&t);
let (phase_status, phase_age_secs) =
Self::runtime_fields(runtime.iter().find(|r| r.task_id == t.id), t.status);
let hook = t.worktree_path.as_ref().and_then(|wt| {
crate::agent::hook_status::read_status(std::path::Path::new(wt), &t.id, now)
});
let mark = TaskMark {
status: t.status,
phase_status: phase_status.clone(),
turn_ts: Self::turn_ts(hook.as_ref()),
deps_satisfied,
escalation_note: t.escalation_note.clone(),
};
let summary = TaskSummary {
phase_status,
phase_age_secs,
id: t.id,
title: t.title,
description: t.description.filter(|_| include_description),
status: t.status.as_str().to_string(),
agent: t.agent,
branch_name: t.branch_name,
pr_url: t.pr_url,
plugin: t.plugin,
referenced_tasks: t.referenced_tasks,
base_branch: t.base_branch,
escalation_note: t.escalation_note,
deps_satisfied,
};
(summary, mark)
})
.collect()
}
/// Record what a read tool just showed the caller, so the next wait does
/// not wake to show it again.
fn remember_seen<'a>(
&self,
project_id: Option<&str>,
seen: impl IntoIterator<Item = (&'a str, &'a TaskMark)>,
tui_connected: bool,
) {
if let Ok(key) = self.project_key(project_id) {
self.with_board(&key, |b| b.view.mark_seen(seen, tui_connected));
}
}
/// One pass of a wait. Synchronous on purpose: the database handle and the
/// lock both stay inside it, so nothing is held across the wait's sleep.
fn poll_board(&self, project_id: Option<&str>, key: &str) -> Result<BoardPoll, String> {
// A wait is a reader for its whole length, not just when it starts: the
// TUI stops publishing phase status once nobody has read it for a while.
self.note_board_watched(project_id);
let db = self.open_project_db_for(project_id)?;
let tasks = db
.get_all_tasks()
.map_err(|e| format!("Error listing tasks: {}", e))?;
let snapshot = Self::board_snapshot(&db, tasks, false);
let tui_connected = self.tui_connected(project_id);
let marks: Vec<(String, TaskMark)> = snapshot
.iter()
.map(|(s, m)| (s.id.clone(), m.clone()))
.collect();
let wake = self.with_board(key, |board| {
// A failed move wakes: nothing on the board shows it, so it is the
// one outcome the caller cannot learn any other way. A completed
// one does not β the status it changed is already on the board.
let mut failed = false;
for q in std::mem::take(&mut board.queued) {
match db.get_transition_request(&q.request_id) {
Ok(Some(req)) if req.processed_at.is_some() => {
failed |= req.error.is_some();
board.resolved.push(ResolvedTransition {
request_id: q.request_id,
task_id: q.task_id,
action: q.action,
status: if req.error.is_some() {
"error"
} else {
"completed"
}
.to_string(),
error: req.error,
});
}
// Processed requests are deleted after an hour; one gone
// before a wait saw it has nothing left to report.
Ok(None) => {}
_ => board.queued.push(q),
}
}
board.view.poll(&marks, tui_connected) || failed
});
Ok(BoardPoll {
snapshot,
tui_connected,
wake,
})
}
/// Answer a wait with what changed, and record that the caller has seen it.
fn answer_wait(&self, key: &str, poll: BoardPoll, timed_out: bool) -> String {
let marks: Vec<(String, TaskMark)> = poll
.snapshot
.iter()
.map(|(s, m)| (s.id.clone(), m.clone()))
.collect();
let (diff, transitions) = self.with_board(key, |board| {
(
board.view.report(&marks, poll.tui_connected),
std::mem::take(&mut board.resolved),
)
});
let changed: std::collections::HashSet<String> = diff.changed.into_iter().collect();
let changes = BoardChanges {
tui_connected: poll.tui_connected,
timed_out,
tasks: poll
.snapshot
.into_iter()
.filter(|(s, _)| changed.contains(&s.id))
.map(|(s, _)| s)
.collect(),
removed: diff.removed,
transitions,
};
serde_json::to_string_pretty(&changes)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
/// Tell the TUI someone is reading this board, so it starts publishing
/// `task_runtime`.
///
/// Publishing is gated on a recent reader because a board nobody reads
/// should cost no writes. An MCP client is such a reader β without this the
/// orchestrator and any oneshot session poll a table that is never written,
/// and every task reports no phase status forever.
///
/// Throttled on the same reasoning as the web server's copy: the question
/// it answers resolves in minutes, and `get_task` is called once per task
/// in a polling loop.
fn note_board_watched(&self, project_id: Option<&str>) {
const NOTE_INTERVAL: Duration = Duration::from_secs(30);
let Ok(path) = self.resolve_project_path(project_id) else {
return;
};
let key = path.to_string_lossy().to_string();
{
let mut watched = self.watched.lock().unwrap_or_else(|e| e.into_inner());
if watched.get(&key).is_some_and(|at| at.elapsed() < NOTE_INTERVAL) {
return;
}
watched.insert(key.clone(), Instant::now());
}
if let Ok(db) = Database::open_global() {
let _ = db.note_board_watched(&key);
}
}
/// Whether a TUI has beaten for this project recently enough to be draining
/// the queue and refreshing phase status.
///
/// Without this a caller can only *infer* a dead board from `phase_age_secs`
/// climbing across every task at once β and until it does, a frozen row
/// reads as live state: a task shows `blocked` while its agent works
/// normally.
fn tui_connected(&self, project_id: Option<&str>) -> bool {
let Ok(path) = self.resolve_project_path(project_id) else {
return false;
};
let Ok(db) = Database::open_global() else {
return false;
};
db.tui_is_live(&path.to_string_lossy(), TUI_HEARTBEAT_STALE_AFTER)
.unwrap_or(false)
}
/// The published phase status for a task, as `(status, age_secs)`.
///
/// A row computed for a status the task has since left is withheld: it
/// describes the previous phase, and its `updated_at` is fresh, so age alone
/// cannot catch it. Returning nothing reads as "not yet observed", which is
/// what it is.
fn runtime_fields(
rt: Option<&crate::db::TaskRuntime>,
current: TaskStatus,
) -> (Option<String>, Option<i64>) {
let rt = rt.filter(|r| r.status.map_or(true, |s| s == current));
(
rt.map(|r| r.phase_status.as_str().to_string()),
rt.map(|r| (chrono::Utc::now() - r.updated_at).num_seconds()),
)
}
/// Resolve a project path from an optional `project_id`.
///
/// - In `Project` mode the fixed path is always returned; `project_id` is ignored.
/// - In `Global` mode `project_id` is required and looked up in the global DB.
fn resolve_project_path(&self, project_id: Option<&str>) -> Result<PathBuf, String> {
match &self.mode {
ServerMode::Project(path) => Ok(path.clone()),
ServerMode::Global => {
let pid = project_id.ok_or_else(|| {
"project_id is required in global mode. Call list_projects first to get project IDs.".to_string()
})?;
let global_db = Database::open_global()
.map_err(|e| format!("Failed to open global database: {}", e))?;
match global_db.get_project_by_id(pid) {
Ok(Some(p)) => Ok(PathBuf::from(p.path)),
Ok(None) => Err(format!("Project not found: {}", pid)),
Err(e) => Err(format!("Failed to look up project: {}", e)),
}
}
}
}
/// Open a project DB, resolving the path via `resolve_project_path`.
fn open_project_db_for(&self, project_id: Option<&str>) -> Result<Database, String> {
let path = self.resolve_project_path(project_id)?;
Database::open_project(&path).map_err(|e| format!("Failed to open project database: {}", e))
}
fn open_project_db(&self) -> Result<Database, String> {
self.open_project_db_for(None)
}
fn open_global_db(&self) -> Result<Database, String> {
Database::open_global().map_err(|e| format!("Failed to open global database: {}", e))
}
/// Get the project name from the project path.
fn project_name_for(&self, project_id: Option<&str>) -> String {
match self.resolve_project_path(project_id) {
Ok(path) => path
.file_name()
.map(|n| n.to_string_lossy().to_string())
.unwrap_or_else(|| "unknown".to_string()),
Err(_) => "unknown".to_string(),
}
}
/// Get the default agent and plugin from merged config.
fn config_defaults_for(&self, project_id: Option<&str>) -> (String, Option<String>) {
let global = GlobalConfig::load().unwrap_or_default();
match self.resolve_project_path(project_id) {
Ok(path) => {
let project = ProjectConfig::load(&path).unwrap_or_default();
let agent = project
.default_agent
.unwrap_or_else(|| global.default_agent.clone());
let plugin = project.workflow_plugin.clone();
(agent, plugin)
}
Err(_) => (global.default_agent.clone(), None),
}
}
/// Which `move_task` actions a task permits, as the orchestrator.
///
/// The web API asks the same question as [`CallerKind::Human`] and gets a
/// different answer for Backlog β see [`crate::core::actions`].
fn allowed_actions(&self, task: &Task, deps_satisfied: bool) -> Vec<String> {
crate::core::actions::allowed_actions(task, deps_satisfied, CallerKind::Orchestrator)
}
}
#[tool_router]
impl AgtxMcpServer {
#[tool(description = "List all projects indexed by agtx")]
fn list_projects(&self, _params: Parameters<ListProjectsParams>) -> String {
tracing::info!(tool = "list_projects", "MCP tool called");
match self.open_global_db() {
Ok(db) => match db.get_all_projects() {
Ok(projects) => {
let summaries: Vec<ProjectSummary> = projects
.into_iter()
.map(|p| ProjectSummary {
id: p.id,
name: p.name,
path: p.path,
})
.collect();
serde_json::to_string_pretty(&summaries)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error listing projects: {}", e),
},
Err(e) => e,
}
}
#[tool(
description = "Read the effective agtx configuration for a project β the global config merged with the project's own, which is what actually governs a run. Use this instead of reading ~/.config/agtx/config.toml: that path is not authoritative (AGTX_CONFIG_DIR relocates it), and a project config overrides much of it. Returns auto_trust (whether agents' trust dialogs are answered automatically β an unattended run needs this true), default_agent, per-phase agents, worktree settings, the active workflow plugin, and the paths both files live at."
)]
fn get_config(&self, Parameters(params): Parameters<GetConfigParams>) -> String {
tracing::info!(tool = "get_config", project_id = ?params.project_id, "MCP tool called");
let project_path = match self.resolve_project_path(params.project_id.as_deref()) {
Ok(p) => p,
Err(e) => return e,
};
let global = GlobalConfig::load().unwrap_or_default();
let project = ProjectConfig::load(&project_path).unwrap_or_default();
let merged = crate::config::MergedConfig::merge(&global, &project);
let project_config_path = project_path.join(".agtx").join("config.toml");
let cfg = EffectiveConfig {
global_config_path: GlobalConfig::config_path()
.map(|p| p.to_string_lossy().to_string())
.unwrap_or_else(|_| "<unresolved>".to_string()),
project_config_exists: project_config_path.exists(),
project_config_path: project_config_path.to_string_lossy().to_string(),
auto_trust: merged.auto_trust,
default_agent: merged.default_agent,
phase_agents: serde_json::json!({
"research": merged.phase_agents.research,
"planning": merged.phase_agents.planning,
"running": merged.phase_agents.running,
"review": merged.phase_agents.review,
}),
worktree_enabled: merged.worktree_enabled,
skip_worktree: merged.skip_worktree,
auto_cleanup: merged.auto_cleanup,
base_branch: merged.base_branch,
worktree_dir: merged.worktree_dir,
branch_prefix: merged.branch_prefix,
workflow_plugin: merged.workflow_plugin,
agent_hooks: merged.agent_hooks,
github_url: merged.github_url,
};
serde_json::to_string_pretty(&cfg)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
#[tool(
description = "List tasks for a project, optionally filtered by status (backlog, planning, running, review, done). Descriptions are left out unless include_description is true β get_task has the full task. To watch the board, call wait_for_board_change instead of calling this in a loop. In global mode, project_id is required β call list_projects first."
)]
fn list_tasks(&self, Parameters(params): Parameters<ListTasksParams>) -> String {
tracing::info!(tool = "list_tasks", status = ?params.status, project_id = ?params.project_id, "MCP tool called");
self.note_board_watched(params.project_id.as_deref());
match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => {
let tasks_result = if let Some(status_str) = ¶ms.status {
match TaskStatus::from_str(status_str) {
Some(status) => db.get_tasks_by_status(status),
None => return format!("Invalid status: '{}'. Valid values: backlog, planning, running, review, done", status_str),
}
} else {
db.get_all_tasks()
};
match tasks_result {
Ok(tasks) => {
let snapshot = Self::board_snapshot(
&db,
tasks,
params.include_description.unwrap_or(false),
);
let tui_connected = self.tui_connected(params.project_id.as_deref());
self.remember_seen(
params.project_id.as_deref(),
snapshot.iter().map(|(s, m)| (s.id.as_str(), m)),
tui_connected,
);
let listing = BoardListing {
tui_connected,
tasks: snapshot.into_iter().map(|(s, _)| s).collect(),
};
serde_json::to_string_pretty(&listing)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error listing tasks: {}", e),
}
}
Err(e) => e,
}
}
#[tool(
description = "Get full details of a specific task by its ID. Includes allowed_actions based on the task's current status and plugin rules, and agent_state (working/blocked/waiting/ended) as reported by the agent itself β when it is \"blocked\", blocked_reason names what the agent is waiting for. In global mode, project_id is required β call list_projects first."
)]
fn get_task(&self, Parameters(params): Parameters<GetTaskParams>) -> String {
tracing::info!(tool = "get_task", task_id = %params.task_id, "MCP tool called");
self.note_board_watched(params.project_id.as_deref());
match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => match db.get_task(¶ms.task_id) {
Ok(Some(t)) => {
let deps_ok = db.deps_satisfied(&t);
let allowed = self.allowed_actions(&t, deps_ok);
let blocking = match &t.referenced_tasks {
Some(refs) if !refs.is_empty() => refs
.split(',')
.filter(|s| !s.is_empty())
.filter_map(|ref_id| {
db.get_task(ref_id)
.ok()
.flatten()
.filter(|dep| {
!matches!(dep.status, TaskStatus::Review | TaskStatus::Done)
})
.map(|dep| BlockingTask {
id: dep.id,
title: dep.title,
status: dep.status.as_str().to_string(),
})
})
.collect(),
_ => Vec::new(),
};
// Read the agent's own status file, written by its hooks.
// Works cross-process precisely because it is a file rather
// than TUI state.
let hook = t.worktree_path.as_ref().and_then(|wt| {
crate::agent::hook_status::read_status(
std::path::Path::new(wt),
&t.id,
chrono::Utc::now().timestamp(),
)
});
let agent_state = hook.as_ref().map(|h| {
match h.state {
crate::agent::hook_status::HookState::Working => "working",
crate::agent::hook_status::HookState::Blocked => "blocked",
crate::agent::hook_status::HookState::Waiting => "waiting",
crate::agent::hook_status::HookState::Ended => "ended",
}
.to_string()
});
let blocked_reason = hook.as_ref().and_then(|h| h.message.clone());
let runtime = db.get_task_runtime(¶ms.task_id).ok().flatten();
let (phase_status, phase_age_secs) = Self::runtime_fields(runtime.as_ref(), t.status);
let tui_connected = self.tui_connected(params.project_id.as_deref());
let mark = TaskMark {
status: t.status,
phase_status: phase_status.clone(),
turn_ts: Self::turn_ts(hook.as_ref()),
deps_satisfied: deps_ok,
escalation_note: t.escalation_note.clone(),
};
self.remember_seen(
params.project_id.as_deref(),
[(t.id.as_str(), &mark)],
tui_connected,
);
let detail = TaskDetail {
phase_status,
phase_age_secs,
tui_connected,
id: t.id,
title: t.title,
description: t.description,
status: t.status.as_str().to_string(),
agent: t.agent,
project_id: t.project_id,
session_name: t.session_name,
worktree_path: t.worktree_path,
branch_name: t.branch_name,
pr_number: t.pr_number,
pr_url: t.pr_url,
plugin: t.plugin,
cycle: t.cycle,
referenced_tasks: t.referenced_tasks,
base_branch: t.base_branch,
escalation_note: t.escalation_note,
created_at: t.created_at.to_rfc3339(),
updated_at: t.updated_at.to_rfc3339(),
deps_satisfied: deps_ok,
blocking_tasks: blocking,
allowed_actions: allowed,
agent_state,
blocked_reason,
};
serde_json::to_string_pretty(&detail)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Ok(None) => format!("Task not found: {}", params.task_id),
Err(e) => format!("Error getting task: {}", e),
},
Err(e) => e,
}
}
#[tool(
description = "Block until something on the board needs you, then return only what changed since you last looked (via this tool, list_tasks or get_task). Wakes when a task reaches ready, idle, blocked or exited, reaches Done, becomes startable in Backlog, is escalated, appears or is deleted; when one of your move_task requests fails; or when the TUI connects or disconnects. A task merely starting to work does not wake it. The first call returns the whole board. Also reports the outcome of every move_task you queued, so get_transition_status is not needed. Use this as the polling loop instead of sleeping and calling list_tasks. timed_out: true means nothing needed you. In global mode, project_id is required β call list_projects first."
)]
async fn wait_for_board_change(
&self,
Parameters(params): Parameters<WaitForBoardChangeParams>,
) -> String {
tracing::info!(tool = "wait_for_board_change", timeout_secs = ?params.timeout_secs, "MCP tool called");
let timeout = Duration::from_secs(
params
.timeout_secs
.unwrap_or(DEFAULT_WAIT_SECS)
.clamp(1, MAX_WAIT_SECS),
);
let project_id = params.project_id.as_deref();
let key = match self.project_key(project_id) {
Ok(k) => k,
Err(e) => return e,
};
let started = Instant::now();
loop {
let poll = match self.poll_board(project_id, &key) {
Ok(p) => p,
Err(e) => return e,
};
if poll.wake {
return self.answer_wait(&key, poll, false);
}
if started.elapsed() >= timeout {
return self.answer_wait(&key, poll, true);
}
tokio::time::sleep(WAIT_POLL_INTERVAL).await;
}
}
#[tool(
description = "Queue a task state transition. The agtx TUI will process it and execute all side effects (worktree creation, agent spawning, etc). Use get_transition_status to check completion β a transition out of Backlog waits for the single worktree-setup slot, so it stays 'pending' until its turn. Actions: research (start research phase for backlog task), move_forward, move_to_planning, move_to_running, move_to_review, move_to_done, move_to_done_and_merge (merge the task branch into its base branch in the project checkout first, and stay in Review if it conflicts β for unattended callers that integrate locally instead of through a PR), resume, escalate_to_user (flag task for user attention with an optional reason)"
)]
fn move_task(&self, Parameters(params): Parameters<MoveTaskParams>) -> String {
tracing::info!(tool = "move_task", task_id = %params.task_id, action = %params.action, "MCP tool called");
let valid_actions = crate::core::actions::ACTIONS;
if !valid_actions.contains(¶ms.action.as_str()) {
return format!(
"Invalid action: '{}'. Valid actions: {}",
params.action,
valid_actions.join(", ")
);
}
match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => {
// Verify task exists
let task = match db.get_task(¶ms.task_id) {
Ok(Some(t)) => t,
Ok(None) => return format!("Task not found: {}", params.task_id),
Err(e) => return format!("Error checking task: {}", e),
};
// Eagerly check dependency gates for forward transitions from Backlog
let forward_actions = [
"move_forward",
"move_to_planning",
"move_to_running",
"research",
];
if forward_actions.contains(¶ms.action.as_str())
&& task.status == TaskStatus::Backlog
&& !db.deps_satisfied(&task)
{
return "Cannot advance task: dependencies not in Review/Done. Use get_task to see blocking_tasks.".to_string();
}
let mut req = TransitionRequest::new(¶ms.task_id, ¶ms.action);
req.reason = params.reason.clone();
let request_id = req.id.clone();
match db.create_transition_request(&req) {
Ok(()) => {
if let Ok(key) = self.project_key(params.project_id.as_deref()) {
self.with_board(&key, |b| {
b.queued.push(QueuedMove {
request_id: request_id.clone(),
task_id: params.task_id.clone(),
action: params.action.clone(),
})
});
}
let result = MoveTaskResult {
request_id,
message: format!(
"Transition '{}' queued for task {}. The agtx TUI will process it shortly.",
params.action, params.task_id
),
};
serde_json::to_string_pretty(&result)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error creating transition request: {}", e),
}
}
Err(e) => e,
}
}
#[tool(
description = "Check the status of a queued transition request. Returns pending, completed, or error with details."
)]
fn get_transition_status(
&self,
Parameters(params): Parameters<GetTransitionStatusParams>,
) -> String {
tracing::info!(tool = "get_transition_status", request_id = %params.request_id, "MCP tool called");
match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => match db.get_transition_request(¶ms.request_id) {
Ok(Some(req)) => {
let status = if req.processed_at.is_some() {
if req.error.is_some() {
"error"
} else {
"completed"
}
} else {
"pending"
};
let result = TransitionStatusResult {
request_id: req.id,
status: status.to_string(),
error: req.error,
};
serde_json::to_string_pretty(&result)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Ok(None) => format!("Transition request not found: {}", params.request_id),
Err(e) => format!("Error getting transition status: {}", e),
},
Err(e) => e,
}
}
#[tool(
description = "Check if task branches have merge conflicts with the main branch. Pass a task_id to check one task, or omit it to check all Review tasks. Uses a read-only git check β no files are modified."
)]
fn check_conflicts(&self, Parameters(params): Parameters<CheckConflictsParams>) -> String {
tracing::info!(tool = "check_conflicts", task_id = ?params.task_id, "MCP tool called");
let project_path = match self.resolve_project_path(params.project_id.as_deref()) {
Ok(p) => p,
Err(e) => return e,
};
let main_branch = match crate::git::detect_main_branch(&project_path) {
Ok(b) => b,
Err(e) => return format!("Failed to detect main branch: {}", e),
};
let tasks = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => {
if let Some(task_id) = ¶ms.task_id {
match db.get_task(task_id) {
Ok(Some(t)) => vec![t],
Ok(None) => return format!("Task not found: {}", task_id),
Err(e) => return format!("Error getting task: {}", e),
}
} else {
match db.get_tasks_by_status(TaskStatus::Review) {
Ok(tasks) => tasks,
Err(e) => return format!("Error listing review tasks: {}", e),
}
}
}
Err(e) => return e,
};
let results: Vec<ConflictCheckResult> = tasks
.into_iter()
.map(|t| {
let branch = match &t.branch_name {
Some(b) => b.clone(),
None => {
return ConflictCheckResult {
task_id: t.id,
title: t.title,
branch_name: None,
has_conflicts: false,
conflicting_files: vec![],
error: Some("No branch name set for this task".to_string()),
};
}
};
match crate::git::check_merge_conflicts(&project_path, &main_branch, &branch) {
Ok((has_conflicts, files)) => ConflictCheckResult {
task_id: t.id,
title: t.title,
branch_name: Some(branch),
has_conflicts,
conflicting_files: files,
error: None,
},
Err(e) => ConflictCheckResult {
task_id: t.id,
title: t.title,
branch_name: Some(branch),
has_conflicts: false,
conflicting_files: vec![],
error: Some(format!("{}", e)),
},
}
})
.collect();
let response = CheckConflictsResponse {
main_branch,
results,
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
#[tool(
description = "Fetch and consume pending notifications. Returns new events (task created, phase completed, etc.) and removes them from the queue. Note: notifications are also pushed to your input automatically when you are idle, so you usually don't need to call this manually."
)]
fn get_notifications(&self, Parameters(params): Parameters<GetNotificationsParams>) -> String {
tracing::info!(tool = "get_notifications", "MCP tool called");
match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => match db.consume_notifications() {
Ok(notifs) => {
let items: Vec<NotificationItem> = notifs
.into_iter()
.map(|n| NotificationItem {
message: n.message,
created_at: n.created_at.to_rfc3339(),
})
.collect();
let response = GetNotificationsResponse {
notifications: items,
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error fetching notifications: {}", e),
},
Err(e) => e,
}
}
#[tool(
description = "Read the last N lines of what a task's agent pane shows (default 50), blank rows at the bottom dropped. Use this to understand what the agent is showing β e.g., when a task has been idle for a while. An agent that draws full-screen, like Claude Code, keeps no history outside its visible screen, so nothing older than that screen can be read this way. Ask for only as many lines as you need: the answer stays in your context."
)]
fn read_pane_content(&self, Parameters(params): Parameters<ReadPaneParams>) -> String {
tracing::info!(tool = "read_pane_content", task_id = %params.task_id, "MCP tool called");
let db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let task = match db.get_task(¶ms.task_id) {
Ok(Some(t)) => t,
Ok(None) => return format!("Task not found: {}", params.task_id),
Err(e) => return format!("Error getting task: {}", e),
};
let session_name = match task.session_name {
Some(ref s) => s.clone(),
None => return format!("Task {} has no active session", params.task_id),
};
let lines = params.lines.unwrap_or(50).max(1).min(10000);
let lines_arg = format!("-{}", lines);
let output = Command::new("tmux")
.args([
"-L",
"agtx",
"capture-pane",
"-t",
&session_name,
"-p",
"-S",
&lines_arg,
])
.output();
match output {
Ok(out) => {
let content =
crate::tmux::pane_tail(&String::from_utf8_lossy(&out.stdout), lines as usize);
let response = ReadPaneResponse {
task_id: params.task_id,
session_name,
content,
lines_requested: lines,
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error reading pane content: {}", e),
}
}
#[tool(
description = "Send a message to a task's agent pane (followed by Enter). Works for tasks in Planning, Running or Review. Use this to nudge a stuck agent, answer a CLI prompt (e.g. 'y' for yes), or provide guidance. In Review it is how to give the reviewer a small fix to make in place, without moving the task back to Running β resume is for significant rework."
)]
fn send_to_task(&self, Parameters(params): Parameters<SendToTaskParams>) -> String {
tracing::info!(tool = "send_to_task", task_id = %params.task_id, "MCP tool called");
// Input validation: limit message length and reject null bytes
const MAX_MESSAGE_LENGTH: usize = 4096;
if params.message.len() > MAX_MESSAGE_LENGTH {
return format!(
"Error: message too long ({} bytes, max {})",
params.message.len(),
MAX_MESSAGE_LENGTH
);
}
if params.message.contains('\x00') {
return "Error: message contains null bytes".to_string();
}
let db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let task = match db.get_task(¶ms.task_id) {
Ok(Some(t)) => t,
Ok(None) => return format!("Task not found: {}", params.task_id),
Err(e) => return format!("Error getting task: {}", e),
};
// Review is included so a reviewer can be given a small fix in place;
// see `accepts_task_input`.
if !crate::core::actions::accepts_task_input(task.status) {
return format!(
"Error: task has no agent to receive input (current: {}). send_to_task works for Planning, Running and Review tasks.",
task.status.as_str()
);
}
let session_name = match task.session_name {
Some(ref s) => s.clone(),
None => return format!("Task {} has no active session", params.task_id),
};
// A bracketed paste, then a watched submit: the path agtx uses for every
// other whole message, via `core::input::send_user_text`.
//
// Not a raw `send-keys` of the text, which loses the head of a long
// message. Measured against Claude Code 2.1.268: a
// 1644-byte message typed that way arrived as its last 622 bytes, the first
// 1022 silently dropped, while the same bytes as a bracketed paste arrived
// whole. tmux and the pty are not the cause β a raw-mode `cat` received
// every byte by both methods β the agent's input handling discards the
// start of a large typed burst. The agent then acts on the tail of an
// instruction with its premise gone, which is worse than receiving nothing.
let tmux_ops: Arc<dyn crate::tmux::TmuxOperations> = Arc::new(crate::tmux::RealTmuxOps);
if !crate::core::input::send_user_text(&tmux_ops, &session_name, ¶ms.message, true) {
return format!("Error sending message to {}", session_name);
}
let response = SendToTaskResponse {
task_id: params.task_id,
session_name,
success: true,
message: format!("Message sent: {}", params.message),
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
#[tool(
description = "Create a new task in the Backlog column. Returns the created task's ID. Use create_tasks_batch for multiple tasks with dependencies. In global mode, project_id is required β call list_projects first."
)]
fn create_task(&self, Parameters(params): Parameters<CreateTaskParams>) -> String {
tracing::info!(tool = "create_task", title = %params.title, "MCP tool called");
let db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let (default_agent, default_plugin) =
self.config_defaults_for(params.project_id.as_deref());
let project_name = self.project_name_for(params.project_id.as_deref());
// Validate referenced task IDs exist
if let Some(ref refs) = params.referenced_tasks {
for ref_id in refs.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()) {
match db.get_task(ref_id) {
Ok(Some(_)) => {}
Ok(None) => return format!("Error: referenced task not found: {}", ref_id),
Err(e) => return format!("Error checking referenced task: {}", e),
}
}
}
let mut task = Task::new(¶ms.title, &default_agent, &project_name);
task.description = params.description;
task.plugin = params.plugin.or(default_plugin);
task.referenced_tasks = params.referenced_tasks;
task.base_branch = params.base_branch;
match db.create_task(&task) {
Ok(()) => {
let response = CreateTaskResponse {
id: task.id,
title: task.title,
status: "backlog".to_string(),
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error creating task: {}", e),
}
}
#[tool(
description = "Create multiple tasks at once with index-based dependency wiring. Each task's depends_on field uses 0-based indices into the tasks array (no forward references). Returns all created task IDs. In global mode, project_id is required β call list_projects first."
)]
fn create_tasks_batch(&self, Parameters(params): Parameters<CreateTasksBatchParams>) -> String {
tracing::info!(
tool = "create_tasks_batch",
count = params.tasks.len(),
"MCP tool called"
);
if params.tasks.is_empty() {
return "Error: tasks array is empty".to_string();
}
if params.tasks.len() > 50 {
return "Error: maximum 50 tasks per batch".to_string();
}
// Pass 1: Validate index-based dependencies
for (i, batch_task) in params.tasks.iter().enumerate() {
if let Some(ref deps) = batch_task.depends_on {
let mut seen = std::collections::HashSet::new();
for &dep_idx in deps {
if dep_idx >= i {
return format!(
"Error: task[{}] '{}' has depends_on index {} which is >= its own index {}. Only backward references allowed.",
i, batch_task.title, dep_idx, i
);
}
if !seen.insert(dep_idx) {
return format!(
"Error: task[{}] '{}' has duplicate depends_on index {}.",
i, batch_task.title, dep_idx
);
}
}
}
}
let mut db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let (default_agent, default_plugin) =
self.config_defaults_for(params.project_id.as_deref());
let project_name = self.project_name_for(params.project_id.as_deref());
// Pass 2: Create all tasks, collect IDs
let mut created_tasks: Vec<Task> = Vec::with_capacity(params.tasks.len());
for batch_task in ¶ms.tasks {
let mut task = Task::new(&batch_task.title, &default_agent, &project_name);
task.description = batch_task.description.clone();
task.plugin = batch_task.plugin.clone().or_else(|| default_plugin.clone());
task.base_branch = batch_task.base_branch.clone();
created_tasks.push(task);
}
// Pass 3: Resolve index-based deps to real task IDs
for (i, batch_task) in params.tasks.iter().enumerate() {
if let Some(ref deps) = batch_task.depends_on {
let dep_ids: Vec<String> = deps
.iter()
.map(|&idx| created_tasks[idx].id.clone())
.collect();
created_tasks[i].referenced_tasks = Some(dep_ids.join(","));
}
}
// Insert all tasks atomically β on any failure none are committed
if let Err(e) = db.create_tasks_batch(&created_tasks) {
return format!("Error creating tasks: {}", e);
}
let results: Vec<BatchTaskResponse> = created_tasks
.iter()
.enumerate()
.map(|(i, task)| BatchTaskResponse {
index: i,
id: task.id.clone(),
title: task.title.clone(),
})
.collect();
let response = CreateTasksBatchResponse {
count: results.len(),
created: results,
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
#[tool(
description = "Update a backlog task's fields. Only tasks in Backlog status can be updated. All fields are optional β only provided fields are changed. In global mode, project_id is required β call list_projects first."
)]
fn update_task(&self, Parameters(params): Parameters<UpdateTaskParams>) -> String {
tracing::info!(tool = "update_task", task_id = %params.task_id, "MCP tool called");
let db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let mut task = match db.get_task(¶ms.task_id) {
Ok(Some(t)) => t,
Ok(None) => return format!("Task not found: {}", params.task_id),
Err(e) => return format!("Error getting task: {}", e),
};
if task.status != TaskStatus::Backlog {
return format!(
"Error: can only update Backlog tasks. Task '{}' is in {} status.",
task.title,
task.status.as_str()
);
}
let mut updated_fields = Vec::new();
if let Some(title) = params.title {
task.title = title;
updated_fields.push("title".to_string());
}
if let Some(description) = params.description {
task.description = Some(description);
updated_fields.push("description".to_string());
}
if let Some(plugin) = params.plugin {
task.plugin = Some(plugin);
updated_fields.push("plugin".to_string());
}
if let Some(ref refs) = params.referenced_tasks {
// Validate referenced task IDs exist
for ref_id in refs.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()) {
match db.get_task(ref_id) {
Ok(Some(_)) => {}
Ok(None) => return format!("Error: referenced task not found: {}", ref_id),
Err(e) => return format!("Error checking referenced task: {}", e),
}
}
task.referenced_tasks = Some(refs.clone());
updated_fields.push("referenced_tasks".to_string());
}
if let Some(base_branch) = params.base_branch {
task.base_branch = Some(base_branch);
updated_fields.push("base_branch".to_string());
}
if updated_fields.is_empty() {
return "No fields to update".to_string();
}
match db.update_task(&task) {
Ok(()) => {
let response = UpdateTaskResponse {
id: task.id,
title: task.title,
updated_fields,
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error updating task: {}", e),
}
}
#[tool(
description = "Delete a task. Only tasks in Backlog status can be deleted. In global mode, project_id is required β call list_projects first."
)]
fn delete_task(&self, Parameters(params): Parameters<DeleteTaskParams>) -> String {
tracing::info!(tool = "delete_task", task_id = %params.task_id, "MCP tool called");
let db = match self.open_project_db_for(params.project_id.as_deref()) {
Ok(db) => db,
Err(e) => return e,
};
let task = match db.get_task(¶ms.task_id) {
Ok(Some(t)) => t,
Ok(None) => return format!("Task not found: {}", params.task_id),
Err(e) => return format!("Error getting task: {}", e),
};
if task.status != TaskStatus::Backlog {
return format!(
"Error: can only delete Backlog tasks. Task '{}' is in {} status.",
task.title,
task.status.as_str()
);
}
match db.delete_task(¶ms.task_id) {
Ok(()) => {
let response = DeleteTaskResponse {
id: task.id,
title: task.title,
message: "Task deleted".to_string(),
};
serde_json::to_string_pretty(&response)
.unwrap_or_else(|e| format!("Error serializing: {}", e))
}
Err(e) => format!("Error deleting task: {}", e),
}
}
}
#[tool_handler]
impl ServerHandler for AgtxMcpServer {
fn get_info(&self) -> ServerInfo {
let instructions = match &self.mode {
ServerMode::Global =>
"agtx MCP server (global mode) β control the terminal kanban board for coding agents. \
IMPORTANT: always call list_projects first to get the project_id for your target project, \
then pass it to every other tool call. \
Use list_tasks to see tasks, create_task or create_tasks_batch to add new tasks \
(with optional dependency wiring via referenced_tasks), update_task to modify backlog \
task fields, move_task to transition tasks between phases, get_transition_status to \
check if a transition completed, and delete_task to remove backlog tasks. \
To supervise the board, call wait_for_board_change in a loop rather than sleeping \
and re-listing: it returns only what changed.",
ServerMode::Project(_) =>
"agtx MCP server β control the terminal kanban board for coding agents. \
Use list_tasks to see current tasks, create_task or create_tasks_batch to add new tasks \
(with optional dependency wiring via referenced_tasks), update_task to modify backlog \
task fields, move_task to transition tasks between phases, get_transition_status to \
check if a transition completed, and delete_task to remove backlog tasks. \
To supervise the board, call wait_for_board_change in a loop rather than sleeping \
and re-listing: it returns only what changed.",
};
ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
.with_instructions(instructions)
}
}
pub async fn serve(project_path: Option<PathBuf>) -> anyhow::Result<()> {
let mode = match project_path {
Some(path) => {
// Validate project DB can be opened
Database::open_project(&path)?;
ServerMode::Project(path)
}
None => {
// Global mode β validate global DB can be opened
Database::open_global()?;
ServerMode::Global
}
};
let server = AgtxMcpServer::new(mode);
let service = server.serve(filtered_stdio()).await?;
service.waiting().await?;
Ok(())
}
/// Buffer size for the in-memory pipes bridging real stdio to rmcp.
const PIPE_BUF: usize = 64 * 1024;
/// stdio for rmcp, with pre-handshake requests answered instead of fatal.
///
/// rmcp aborts if the first message is not `initialize`, which Antigravity CLI
/// triggers by probing with `server/discover` first. See `prehandshake` for the
/// full story. Returns a (reader, writer) pair rmcp can serve on; two background
/// tasks pump real stdin/stdout through it.
fn filtered_stdio() -> (tokio::io::DuplexStream, tokio::io::DuplexStream) {
use crate::mcp::prehandshake::{HandshakeFilter, PreInitAction};
use std::sync::Arc;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::sync::Mutex;
// client β us β rmcp
let (mut to_rmcp, rmcp_reader) = tokio::io::duplex(PIPE_BUF);
// rmcp β us β client
let (rmcp_writer, mut from_rmcp) = tokio::io::duplex(PIPE_BUF);
// Both the filter (error replies) and rmcp (real responses) write to stdout.
let stdout = Arc::new(Mutex::new(tokio::io::stdout()));
// Pump 1: real stdin β filter β rmcp.
let filter_stdout = stdout.clone();
tokio::spawn(async move {
let mut lines = BufReader::new(tokio::io::stdin()).lines();
let mut filter = HandshakeFilter::new();
while let Ok(Some(line)) = lines.next_line().await {
match filter.next(&line) {
PreInitAction::Forward => {
if to_rmcp.write_all(line.as_bytes()).await.is_err()
|| to_rmcp.write_all(b"\n").await.is_err()
|| to_rmcp.flush().await.is_err()
{
break;
}
}
PreInitAction::Reject(response) => {
let mut out = filter_stdout.lock().await;
if out.write_all(response.as_bytes()).await.is_err()
|| out.write_all(b"\n").await.is_err()
|| out.flush().await.is_err()
{
break;
}
tracing::debug!(
"answered pre-handshake request with method-not-found: {}",
line
);
}
PreInitAction::Drop => {
tracing::debug!("dropped pre-handshake notification: {}", line);
}
}
}
// EOF on stdin β closing our end shuts rmcp down cleanly.
drop(to_rmcp);
});
// Pump 2: rmcp β real stdout.
tokio::spawn(async move {
let mut buf = vec![0u8; 8192];
loop {
let n = match tokio::io::AsyncReadExt::read(&mut from_rmcp, &mut buf).await {
Ok(0) | Err(_) => break,
Ok(n) => n,
};
let mut out = stdout.lock().await;
if out.write_all(&buf[..n]).await.is_err() || out.flush().await.is_err() {
break;
}
}
});
(rmcp_reader, rmcp_writer)
}