MCP任务文件服务器

Requirements

• Go 1.25 or later

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.

Installation

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

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

Usage

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

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.

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.