Wrapping a CLI as an MCP Server

{"name": "search", "summary": "Search the documentation",
 "args": [{"name": "query", "required": true, "type": "string"}],
 "flags": [{"name": "--component", "type": "string", "required": false},
           {"name": "--limit", "type": "integer", "required": false, "default": 10}],
 "output": {"schema": "https://example.invalid/docsctl/schemas/search.v1.json"},
 "exitCodes": [0, 2, 6, 7],
 "safety": {"readOnly": true, "destructive": false, "idempotent": true, "openWorld": true, "requiresConfirmation": false}}

{"name": "docsctl_search",
 "description": "Search the documentation of this site and return the best matching pages.",
 "inputSchema": {"type": "object",
                 "properties": {"query": {"type": "string", "minLength": 1, "maxLength": 200},
                                "component": {"type": "string"},
                                "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 10}},
                 "required": ["query"]},
 "outputSchema": {"type": "object", "required": ["schemaVersion", "results"], "...": "..."},
 "annotations": {"readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true}}

"""docsctl as an MCP server (FastMCP 4): one CLI subcommand per tool."""
import json
import os
import re
import subprocess
from typing import Annotated

from fastmcp import FastMCP
from fastmcp.exceptions import ToolError
from fastmcp.tools import ToolResult
from pydantic import Field

DOCSCTL = os.environ.get("DOCSCTL_BIN", "/usr/local/bin/docsctl")  # absolute path, fixed at deploy time
MAX_STDOUT_BYTES = 256_000                                        # output-size cap
NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")              # cannot start with "-"

SEARCH_OUTPUT = {  # in a real build: generated from `docsctl schema --json` (output.schema)
    "type": "object",
    "properties": {
        "schemaVersion": {"const": 1},
        "query": {"type": "string"},
        "total": {"type": "integer"},
        "nextCursor": {"type": ["string", "null"]},
        "truncated": {"type": "boolean"},
        "results": {"type": "array", "items": {"type": "object"}},
    },
    "required": ["schemaVersion", "results"],
}

mcp = FastMCP("docsctl", version="0.1.0")


def checked_name(value: str) -> str:
    """Allowlist validation: reject anything that is not a plain name (and so anything starting with "-")."""
    if not NAME.fullmatch(value):
        raise ToolError(f"invalid component name {value!r}: letters, digits, '.', '_' and '-' only, not starting with '-'")
    return value


def run_docsctl(argv: list[str]) -> ToolResult:
    """Run docsctl with an argv list (never a shell string) and map its result to MCP."""
    env = {"PATH": "/usr/bin:/bin", "DOCSCTL_NO_INPUT": "1"}       # minimal environment
    if "DOCSCTL_TOKEN" in os.environ:                              # pass only what the CLI needs
        env["DOCSCTL_TOKEN"] = os.environ["DOCSCTL_TOKEN"]
    try:
        proc = subprocess.run([DOCSCTL, *argv], shell=False, capture_output=True, text=True,
                              timeout=25, env=env, stdin=subprocess.DEVNULL)
    except subprocess.TimeoutExpired:
        raise ToolError("docsctl timed out after 25 s; retry with a narrower query.")
    if len(proc.stdout) > MAX_STDOUT_BYTES:
        raise ToolError("docsctl output exceeded the size cap; use --limit or a narrower query.")
    if proc.returncode == 0:
        doc = json.loads(proc.stdout)
        return ToolResult(content=proc.stdout, structured_content=doc)   # JSON stdout -> structuredContent
    # exit code != 0 -> isError: pass the CLI's own error envelope (it carries hint and confirm command)
    raise ToolError(f"docsctl exited {proc.returncode}: {proc.stderr.strip()[:4000]}")


@mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True,
                       "openWorldHint": True},
          output_schema=SEARCH_OUTPUT)
def docsctl_search(
    query: Annotated[str, Field(min_length=1, max_length=200, description="Free-text query")],
    component: Annotated[str | None, Field(description="Restrict to one component")] = None,
    limit: Annotated[int, Field(ge=1, le=100)] = 10,
) -> ToolResult:
    """Search the documentation of this site and return the best matching pages."""
    argv = ["search", "--json", "--no-input", "--limit", str(limit)]
    if component:
        argv += ["--component", checked_name(component)]
    return run_docsctl([*argv, "--", query])                       # "--" before the user operand


@mcp.tool(annotations={"readOnlyHint": False, "destructiveHint": True, "idempotentHint": True,
                       "openWorldHint": True})
def docsctl_publish(
    component: Annotated[str, Field(description="Component to publish")],
    dry_run: bool = True,
) -> ToolResult:
    """Plan (default) or attempt to publish a component; a real publish needs a human to confirm."""
    argv = ["publish", "--json", "--no-input", "--component", checked_name(component)]
    if dry_run:
        argv.append("--dry-run")
    return run_docsctl(argv)                                       # exit 5 -> isError with the confirm command


if __name__ == "__main__":
    mcp.run()                                                      # stdio

import asyncio
from fastmcp import Client
import server

async def main():
    async with Client(server.mcp) as client:
        ok = await client.call_tool("docsctl_search", {"query": "-h kalman"})
        print(ok.structured_content["results"])          # []  the leading "-h" was treated as an operand
        bad = await client.call_tool("docsctl_search", {"query": "x", "component": "--evil"}, raise_on_error=False)
        print(bad.is_error, bad.content[0].text)         # True invalid component name '--evil': ...

asyncio.run(main())

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { McpServer, type CallToolResult } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';

const run = promisify(execFile);
const DOCSCTL = process.env.DOCSCTL_BIN ?? '/usr/local/bin/docsctl'; // absolute path, fixed at deploy time
const MAX_BYTES = 256_000;                                           // output-size cap (execFile maxBuffer)
const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;                    // cannot start with "-"

const searchOutput = z.object({
    schemaVersion: z.literal(1),
    query: z.string(),
    total: z.number().int(),
    nextCursor: z.string().nullable(),
    truncated: z.boolean(),
    results: z.array(z.record(z.string(), z.unknown()))
});

async function runDocsctl(argv: string[]): Promise<CallToolResult> {
    const env: Record<string, string> = { PATH: '/usr/bin:/bin', DOCSCTL_NO_INPUT: '1' };  // minimal environment
    if (process.env.DOCSCTL_TOKEN) env.DOCSCTL_TOKEN = process.env.DOCSCTL_TOKEN;
    try {
        const { stdout } = await run(DOCSCTL, argv, { timeout: 25_000, maxBuffer: MAX_BYTES, env, shell: false });
        return { content: [{ type: 'text', text: stdout }], structuredContent: JSON.parse(stdout) };  // JSON stdout -> structuredContent
    } catch (err) {
        const e = err as { code?: number | string; killed?: boolean; stderr?: string };
        const why = e.killed ? 'timed out' : `exited ${e.code}`;
        // non-zero exit -> isError: the CLI's error envelope (hint, confirm command) is the message
        return { isError: true, content: [{ type: 'text', text: `docsctl ${why}: ${(e.stderr ?? '').slice(0, 4000)}` }] };
    }
}

export function createDocsctlServer(): McpServer {
    const server = new McpServer({ name: 'docsctl', version: '0.1.0' });

    server.registerTool(
        'docsctl_search',
        {
            title: 'Search the documentation',
            description: 'Search the documentation of this site and return the best matching pages.',
            inputSchema: z.object({
                query: z.string().min(1).max(200),
                component: z.string().regex(NAME).optional(),
                limit: z.number().int().min(1).max(100).default(10)
            }),
            outputSchema: searchOutput,
            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
        },
        async ({ query, component, limit }) => {
            const argv = ['search', '--json', '--no-input', '--limit', String(limit)];
            if (component) argv.push('--component', component);
            return runDocsctl([...argv, '--', query]);              // "--" before the user operand
        }
    );

    return server;
}

package com.example;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import java.util.regex.Pattern;
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;
import tools.jackson.databind.json.JsonMapper;

@Component
public class DocsctlTools {

    private static final String DOCSCTL = System.getProperty("docsctl.bin", "/usr/local/bin/docsctl"); // absolute path
    private static final int MAX_STDOUT_BYTES = 256_000;                                               // output-size cap
    private static final int MAX_STDERR_BYTES = 4_000;                                                 // kept for the error message
    private static final Pattern NAME = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._-]{0,63}");            // cannot start with "-"
    private static final JsonMapper JSON = JsonMapper.builder().build();

    public record SearchResult(int schemaVersion, String query, long total, String nextCursor,
                               boolean truncated, List<Map<String, Object>> results) {}

    @McpTool(name = "docsctl_search",
            description = "Search the documentation of this site and return the best matching pages.",
            generateOutputSchema = true,
            annotations = @McpTool.McpAnnotations(readOnlyHint = true, destructiveHint = false,
                    idempotentHint = true, openWorldHint = true))
    public SearchResult search(
            @McpToolParam(description = "Free-text query", required = true) String query,
            @McpToolParam(description = "Restrict to one component", required = false) String component,
            @McpToolParam(description = "Maximum number of results, 1 to 100", required = false) Integer limit) {
        int n = limit == null ? 10 : limit;
        if (n < 1 || n > 100 || query == null || query.isBlank() || query.length() > 200) {
            throw new IllegalArgumentException("query must be 1-200 characters and limit 1-100");
        }
        List<String> argv = new ArrayList<>(List.of(DOCSCTL, "search", "--json", "--no-input", "--limit", String.valueOf(n)));
        if (component != null) {
            if (!NAME.matcher(component).matches()) {
                throw new IllegalArgumentException("invalid component name");
            }
            argv.addAll(List.of("--component", component));
        }
        argv.addAll(List.of("--", query));                       // "--" before the user operand
        return JSON.readValue(runDocsctl(argv), SearchResult.class);   // JSON stdout -> structured content
    }

    static String runDocsctl(List<String> argv) {
        try {
            return start(argv);
        } catch (IOException e) {                                // a RuntimeException becomes isError: true
            throw new IllegalStateException("could not start docsctl: " + e.getMessage(), e);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("interrupted while waiting for docsctl", e);
        }
    }

    private static String start(List<String> argv) throws IOException, InterruptedException {
        ProcessBuilder pb = new ProcessBuilder(argv);            // an argv list, never "sh -c <string>"
        pb.environment().clear();                                // minimal environment
        pb.environment().put("PATH", "/usr/bin:/bin");
        pb.environment().put("DOCSCTL_NO_INPUT", "1");
        String token = System.getenv("DOCSCTL_TOKEN");
        if (token != null) {
            pb.environment().put("DOCSCTL_TOKEN", token);        // pass only what the CLI needs
        }
        Process p = pb.start();
        p.getOutputStream().close();                             // no stdin
        CompletableFuture<byte[]> out = CompletableFuture.supplyAsync(() -> readOrKill(p, MAX_STDOUT_BYTES));
        CompletableFuture<byte[]> err = CompletableFuture.supplyAsync(() -> readAndDiscard(p.getErrorStream(), MAX_STDERR_BYTES));
        if (!p.waitFor(25, TimeUnit.SECONDS)) {
            kill(p);
            throw new IllegalStateException("docsctl timed out after 25 s; retry with a narrower query");
        }
        byte[] stdout = out.join();
        if (stdout.length > MAX_STDOUT_BYTES) {                  // readOrKill has already stopped the child
            throw new IllegalStateException("docsctl output exceeded the size cap; use a smaller limit");
        }
        if (p.exitValue() != 0) {                                // non-zero exit -> RuntimeException -> isError: true
            throw new IllegalStateException("docsctl exited " + p.exitValue() + ": "
                    + new String(err.join(), StandardCharsets.UTF_8).strip());
        }
        return new String(stdout, StandardCharsets.UTF_8);
    }

    /** Reads at most max + 1 bytes of stdout; one byte more than the cap means "too large", so the child is killed. */
    private static byte[] readOrKill(Process p, int max) {
        try {
            byte[] data = p.getInputStream().readNBytes(max + 1);
            if (data.length > max) {
                kill(p);                                         // stop a runaway producer instead of blocking it
            }
            return data;
        } catch (IOException e) {
            return new byte[0];
        }
    }

    /** Keeps the first max bytes of stderr and discards the rest, so a chatty child never blocks on a full pipe. */
    private static byte[] readAndDiscard(InputStream in, int max) {
        try {
            byte[] head = in.readNBytes(max);
            in.transferTo(OutputStream.nullOutputStream());
            return head;
        } catch (IOException e) {
            return new byte[0];
        }
    }

    private static void kill(Process p) {
        p.descendants().forEach(ProcessHandle::destroyForcibly); // grandchildren first, while they are still descendants
        p.destroyForcibly();
    }
}