mcp-taskfile-server

MCP Taskfile Server

A Model Context Protocol (MCP) server that dynamically exposes Taskfile.yml tasks as individual MCP tools, allowing AI assistants to discover and execute any task defined in your Taskfile.

Built using the official Go MCP SDK for MCP protocol implementation and the go-task library for native Taskfile.yml parsing and execution.

Why

• Standard practices for building, linting, etc. are already defined in a Taskfile. Allow the assistant to execute these tasks directly.
• Parity between local, CI and AI.
• Seemed like a fun idea.

Features

• Dynamic Task Discovery: Automatically discovers all tasks from Taskfile.yml at runtime
• Individual Task Tools: Each task becomes its own MCP tool with proper schema
• Variable Schema Generation: Automatically extracts task variables for proper parameter validation
• Native Task Execution: Uses go-task library directly (no subprocess execution)
• Multi-Root Support: Discovers roots via the MCP Roots capability, loading Taskfiles from each root directory
• Auto Reload: Watches each root's resolved local Taskfile graph for changes and automatically re-exposes updated tools to connected clients
• MCP Protocol Compliance: Uses the official Go MCP SDK for full specification compliance

Requirements

• Go 1.25 or later

Installation

go install github.com/rsclarke/mcp-taskfile-server@latest

This places the mcp-taskfile-server binary in $GOBIN (or $GOPATH/bin).

Usage

Running the Server

The server communicates via JSON-RPC over stdin/stdout:

mcp-taskfile-server

Root Discovery

After the client handshake completes, the server calls roots/list to discover which directories to load Taskfiles from. Clients that support the MCP Roots capability can provide one or more file:// root URIs. If the client does not support roots (returns JSON-RPC -32601), the server falls back to the current working directory.

Each root is expected to be the directory that directly contains the top-level Taskfile for that workspace. The server checks only that exact root directory for supported Taskfile filenames and does not walk parent directories.

Equivalent local file URI aliases are canonicalized before they enter server state, so values such as file:///repo and file://localhost/repo share a single internal root identity.

When roots change at runtime (notifications/roots/list_changed), the server diffs the root set, tears down removed roots (cancelling their per-root watcher goroutine and unregistering their tools), and loads any newly added roots.

Roots whose initial Taskfile load fails are kept as unloaded placeholders: the workdir is recorded and the root directory is watched for the standard Taskfile filenames so a Taskfile created or fixed after startup is automatically picked up. Placeholder roots expose zero MCP tools.

Dynamic Tool Discovery

The server automatically discovers all tasks in each root's Taskfile.yml and exposes each as an individual MCP tool. Roots that contain no public tasks are still loaded successfully; they simply expose zero MCP tools until public tasks appear.

Each tool automatically includes:

• Task-specific variables: Extracted from the task definition with proper defaults
• Proper descriptions: Uses task descriptions from Taskfile.yml

Tool Name Mapping

Taskfile task names can contain characters such as :, *, spaces, /, and non-ASCII text that are not MCP-valid tool names. The server automatically sanitizes exported tool names to conform to the MCP tool name specification ([a-zA-Z0-9_.-], max length 128).

Naming Rules

When the tool name differs from the original task name, the original is included in the tool description for discoverability. If a sanitized tool name would exceed 128 characters, it is truncated and given a deterministic hash suffix. If multiple tasks resolve to the same final MCP tool name after sanitization and optional root prefixing, all of those colliding tasks are excluded from MCP exposure.

Multi-Root Prefixing

With a single root, tool names are unprefixed (as shown above). When the client provides multiple roots, each tool name is prefixed with a sanitized form of the root directory's basename to avoid collisions:

The prefix is derived from the directory basename with non-alphanumeric characters (except _, -, .) replaced by underscores. If a root is added or removed such that the count crosses the 1↔N boundary, all tools are re-registered with or without prefixes accordingly.

Wildcard Tasks

Taskfile wildcard tasks (e.g. start:*) are exposed as tools with a required MATCH parameter. MATCH is a JSON array of strings with one entry per * segment in the task name; the schema sets minItems and maxItems to that count so wrong-arity calls fail validation before the handler runs. The server substitutes each entry into the corresponding * segment to reconstruct the full task name at invocation time.

For a task defined as start:*, calling the tool:

{"name": "start", "arguments": {"MATCH": ["web"]}}

executes task start:web.

For tasks with multiple wildcards (e.g. deploy:*:*), provide one array element per wildcard segment, in order. Empty strings are rejected:

{"name": "deploy", "arguments": {"MATCH": ["api", "production"]}}

executes task deploy:api:production.

Breaking change: previous releases accepted MATCH as a single comma-separated string (e.g. "api,production"). Update clients to send a JSON array of strings instead. Values may now safely contain commas.

Tool Result Shape

Each task invocation returns a CallToolResult with up to three TextContent blocks so clients can render or filter streams independently:

1. Status block (always present): a one-line summary such as Task build exited with status 0. Failing tasks surface the underlying exit code reported by go-task (e.g. Task fail exited with status 7: ...); non-exec failures (such as setup errors) fall back to Task failed: <error>.
2. Stdout block (if non-empty): the captured standard output, with Meta: {"stream": "stdout"}.
3. Stderr block (if non-empty): the captured standard error, with Meta: {"stream": "stderr"}.

IsError is set to true whenever the underlying task returns an error, so clients can react to failure without parsing the status line.

MCP Integration

This server implements the Model Context Protocol and can be used with any MCP-compatible client or AI assistant. The server:

1. Requests roots from the client after handshake; falls back to the working directory if unsupported
2. Dynamically discovers all tasks from each root's Taskfile.yml
3. Sanitizes task names into valid MCP tool names for strict client compatibility
4. Exposes each task as an individual MCP tool with proper JSON schema
5. Automatically extracts task variables for parameter validation
6. Reacts to root changes by adding/removing roots and re-syncing tools at runtime
7. Executes tasks natively using the go-task library (no subprocess calls)
8. Provides comprehensive error handling and feedback

Auto Reload

The server resolves each root's Taskfile graph using go-task, then watches the parent directories for every local Taskfile in that graph using fsnotify. Each root has its own watcher goroutine, owned by a per-server watch.Manager, so adding or removing a root only spawns or cancels that root's watcher and never disturbs the others. When one of the watched Taskfiles is modified, added, or removed, the server automatically:

1. Reloads and re-parses the root's Taskfile graph
2. Diffs the updated tool set against currently registered tools
3. Adds new tools and removes stale ones via the MCP SDK
4. Notifies connected clients of the change (notifications/tools/list_changed)

After each reload, the watcher re-reads the root's watch state so newly included local Taskfiles start being watched and removed ones stop being watched. File system events are debounced (~200 ms) to avoid redundant reloads during rapid edits. Watchers run for the lifetime of the root and are cancelled on root removal or server shutdown.

If a root Taskfile becomes invalid or is deleted, the root is replaced with a fresh placeholder that preserves the workdir and watch set but has no loaded Taskfile, so the root's tools are withdrawn until a valid Taskfile is restored.

Logging

The server emits structured JSON logs to stderr using log/slog. With the stdio MCP transport, stderr is the only safe channel for diagnostics; stdout is reserved for JSON-RPC traffic.

Each line is a single JSON object with at least:

• time, level, msg
• service and version of this server
• An event field naming the specific occurrence (e.g. root.load_failed, tools.collision, watcher.reload_failed)
• Contextual fields where applicable: root_uri, tool_name, error

The default level is info. Set the MCP_TASKFILE_LOG_LEVEL environment variable to one of debug, info, warn, or error to change it (case-insensitive). Unrecognised values fall back to info.

MCP_TASKFILE_LOG_LEVEL=debug mcp-taskfile-server

MCP Logging Capability

In addition to writing to stderr, the server advertises the MCP logging capability and mirrors every record through the active session as a notifications/message notification using the Go SDK's mcp.LoggingHandler. The two sinks are independent:

• Stderr is the source of truth and is gated by MCP_TASKFILE_LOG_LEVEL.
• MCP forwarding is gated by the client-set threshold via logging/setLevel. Until the client raises the level, the SDK suppresses every record, so connecting clients see no log noise unless they opt in.

The structured attributes (event, root_uri, tool_name, error, etc.) are forwarded verbatim as the notification's data payload so clients can filter on them. The MCP arm is wired in only after the client handshake completes; records emitted earlier reach stderr alone.

Note: the server is built around a single MCP session per process — Server.Run over stdio binds exactly one — so the in-band logging stream is always unambiguously scoped to "this client". Multi-tenant HTTP deployments are out of scope today; if added, the recommended pattern is one *mcp.Server per session via NewStreamableHTTPHandler's getServer factory, which preserves this 1:1 invariant.

Error Handling

The server handles various error conditions:

• Missing Taskfile.yml
• Invalid task names
• Task execution failures
• Invalid MCP requests

All errors are returned following MCP error response format.

Security Considerations

This server executes arbitrary commands defined in your Taskfile. Only use it in trusted environments and ensure your Taskfile doesn't contain malicious commands.

Development

Package Layout

The server is split into small, single-purpose packages under internal/:

• internal/server — Orchestrator. Owns the *Server value, the root map, the registered-tool map, the generation counter, and the lifecycle handlers wired into the MCP SDK (HandleInitialized, HandleRootsChanged).
• internal/roots — Loads and represents Taskfile roots. Owns the Root value type, URI canonicalisation, and Taskfile graph resolution. Does not depend on the MCP SDK.
• internal/tools — Pure planning. Translates root snapshots into MCP-shaped tools, handles name sanitisation, collision detection, multi-root prefixing, wildcard MATCH schemas, and the plan/diff that the orchestrator applies.
• internal/exec — Per-call task execution handlers, including stdout/stderr capture and the status/stream TextContent blocks returned to clients.
• internal/watch — Per-root fsnotify watcher lifecycle. A watch.Manager spawns at most one goroutine per root URI and exposes Apply / Reconcile / Shutdown.
• internal/logging — Structured logging primitives: stderr handler construction, the MCP logging arm, and a FanoutHandler that mirrors records to both sinks.

Lifecycle

1. Server Setup: The MCP server is created with mcp.NewServer() using InitializedHandler and RootsListChangedHandler. The orchestrator is constructed with server.New() and attached to the MCP server via SetToolRegistry.
2. Logger Wiring: SetLogger() swaps the active *slog.Logger atomically; HandleInitialized() extends it with the MCP arm bound to the active session so subsequent records reach the client through notifications/message.
3. Root Discovery: HandleInitialized() calls ListRoots on the session (falling back to the working directory on -32601) and initializeRoots() loads them. HandleRootsChanged() calls replaceRoots() to reconcile the live set against the client's updated list.
4. Snapshot / Plan / Apply: syncTools() follows a three-phase pattern — snapshot state under lock, call tools.BuildPlan without the lock, then re-acquire the lock, validate the generation, and apply the diff to the MCP registry.
5. Generation Guard: Each state mutation (root add/remove, root reload, placeholder swap) increments a generation counter. If another mutator runs while a plan is being built, the stale plan is discarded — that mutator will produce its own sync.
6. Tool Generation: For each non-internal task, tools.CreateToolForTask builds the MCP tool with extracted variables and (for wildcard tasks) a MATCH array schema sized to the wildcard count.
7. Handler Creation: During planning, each task gets a per-call handler via exec.NewHandler(workdir, taskName) bound to the root's workdir.
8. Native Execution: The handler builds a fresh task.Executor per call (silent mode, captured stdout/stderr) and invokes executor.Run() from the go-task library, returning a CallToolResult with the status/stdout/stderr blocks described above.
9. Watching: watch.Manager.Apply() spawns a goroutine per newly added root that runs watch.Watch(). On each debounced filesystem event the watcher calls back into the orchestrator via Server.ReloadRoot(), which rebuilds the root through roots.Build() and triggers another syncTools().

Key Components

internal/server

• New(): Constructs an empty orchestrator with a discard logger and a fresh watch.Manager. Roots are loaded after the client handshake.
• SetLogger() / SetToolRegistry(): Wire the structured logger and the MCP server (used as the tool registry) into the orchestrator.
• HandleInitialized(): Installs the MCP logging arm onto the active logger, then calls initializeRootsFromSession().
• HandleRootsChanged(): Lists roots from the session, calls replaceRoots(), syncs tools, and applies the per-root watcher diff.
• initializeRoots() / replaceRoots(): Reconcile the root map against a desired set of MCP roots. Both return a reconcileResult with the added/removed canonical URIs so callers can drive syncTools() and watch.Manager.Apply() outside the lock.
• ReloadRoot(): Rebuilds a single root via roots.Build() and re-syncs tools. On failure the root is replaced with a placeholder via disableRootToolsLocked() so its tools are withdrawn until the Taskfile is restored.
• syncTools(): Orchestrates the snapshot/plan/apply cycle with generation validation to safely update registered tools.
• snapshotToolStateLocked(): Captures the current root map and generation under lock for use by tools.BuildPlan.
• RootWatchState() / Shutdown(): Implement the watch.StateProvider contract; Shutdown cancels every per-root watcher and waits for them to exit.

internal/roots

• Build() / Load(): Resolve a workdir's Taskfile graph, set up a task.Executor, and return a populated *Root.
• NewUnloaded(): Returns a placeholder *Root for a directory whose Taskfile cannot currently be loaded; the directory is still watched for the standard Taskfile filenames.
• CanonicalRootURI() / DirToURI(): Canonicalise local file:// URIs so equivalent aliases share one identity.
• loadTaskfileWatchSet(): Resolves the local Taskfile graph and derives the parent directories and exact Taskfile paths to watch.

internal/tools

• BuildPlan(): Computes the desired MCP tool set and handlers from a StateSnapshot without mutating the orchestrator; logs and excludes colliding tool names.
• CreateToolForTask(): Generates the MCP tool definition, schema, and description for a single task.
• Diff(): Compares old registered tools against desired tools by serialized schema bytes and returns stale/added name lists.
• Naming helpers: RootPrefix() and the sanitisation helpers implement the rules in Tool Name Mapping.

internal/exec

• NewHandler(): Returns an mcp.ToolHandler bound to a root workdir and task name. The handler resolves wildcard MATCH arguments, runs the task with captured streams, and produces the status/stdout/stderr TextContent blocks.

internal/watch

• Manager: Spawns and tracks per-root watcher goroutines. Apply() performs an additive/removal diff; Reconcile() converges to a desired URI set; Shutdown() cancels every watcher and waits for them to drain.
• Watch(): Per-root fsnotify loop. Calls StateProvider.RootWatchState() for the directories to subscribe to and the Taskfile paths whose modification triggers a debounced reload via StateProvider.ReloadRoot().

internal/logging

• NewLogger(): Stderr JSON *slog.Logger gated by MCP_TASKFILE_LOG_LEVEL and tagged with service / version.
• InstallMCP(): Wraps an existing logger so each record is also forwarded as an MCP notifications/message on the active session.
• FanoutHandler: Dispatches a single record to multiple slog.Handlers (stderr + MCP) without coupling their lifecycles.

Key Dependencies

• Go MCP SDK: Official MCP protocol implementation
• go-task: Native Taskfile.yml parsing and execution
• fsnotify: Cross-platform file system notifications for auto reload

The server uses the go-task library's native API for both parsing and execution, ensuring maximum compatibility with Taskfile.yml features.