Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

mcp: an MCP server so AI coding assistants can install and run colibri

JustVugg5fd5e057698a
diff --git a/c/Makefile b/c/Makefile
index 3c125d39..d7f55a5e 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -2667,7 +2667,7 @@ install: colibri$(EXE) glm53$(EXE) inkling$(EXE) kimi_k3$(EXE) olmoe$(EXE) qwen3
$(INSTALL) -m 644 family_registry.py resource_plan.py doctor.py autotune.py \
openai_server.py cluster.py v4_dsml.py v41_dsml.py version.py \
image_engine.py term_image.py setup_flow.py setup_hw.py setup_catalog.py \
- setup_download.py $(DESTDIR)$(LIBEXECDIR)/
+ setup_download.py mcp_server.py $(DESTDIR)$(LIBEXECDIR)/
$(INSTALL) -m 644 tools/*.py $(DESTDIR)$(LIBEXECDIR)/tools/
@# The dashboard is an optional build artifact (cd web && npm run build), so install
@# it only when it exists. It goes NEXT TO openai_server.py, which probes ./web/dist.
diff --git a/c/coli b/c/coli
index 49abae39..80dc2d41 100755
--- a/c/coli
+++ b/c/coli
@@ -3466,6 +3466,7 @@ def main():
plogs=sub.add_parser("logs",help="the last lines of the background server (or install) log")
plogs.add_argument("-n","--lines",type=int,default=100)
plogs.add_argument("--install",action="store_true",help="the install log instead of the server's")
+ sub.add_parser("mcp",help="Model Context Protocol server on stdio, for AI coding assistants")
pb=sub.add_parser("bench", parents=[common]); pb.add_argument("tasks", nargs="*")
pb.add_argument("--limit",type=int,default=40)
if sys.platform == "win32":
@@ -3498,6 +3499,9 @@ def main():
flow={"setup":setup_flow.cmd_setup,"start":setup_flow.cmd_start,
"status":setup_flow.cmd_status,"logs":setup_flow.cmd_logs}[a.cmd]
sys.exit(setup_flow.run(flow,a))
+ if a.cmd=="mcp":
+ import mcp_server
+ sys.exit(mcp_server.main())
if a.cmd=="cluster":
if a.cluster_cmd=="coordinator": handler=cmd_cluster_coordinator
elif a.cluster_cmd=="worker": handler=cmd_cluster_worker
diff --git a/c/mcp_server.py b/c/mcp_server.py
new file mode 100644
index 00000000..f4e9ff48
--- /dev/null
+++ b/c/mcp_server.py
@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+"""colibri as a Model Context Protocol server, over stdio.
+
+An AI coding assistant starts this process and talks JSON-RPC 2.0 to it, one
+JSON message per line on stdin and stdout (the MCP stdio transport). Nothing
+else may reach stdout: diagnostics go to stderr.
+
+Tools, all thin wrappers over setup_flow.py (the same code `coli setup` runs):
+
+ detect_hardware RAM, disk, CPU features, GPUs (Vulkan, NVIDIA)
+ recommend_models the catalog against this machine, with the default marked
+ install build or fetch the engine and download a model, as a
+ background job that survives this server; progress is
+ reported with notifications/progress while waiting
+ start / stop the configured server (background)
+ status setup, install progress, server state, URLs, tok/s
+ logs the tail of the server, install or build log
+
+Run it with `coli mcp`, or `python3 c/mcp_server.py`. docs/MCP_SERVER.md has
+the client configuration.
+"""
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import traceback
+
+HERE = os.path.dirname(os.path.realpath(__file__))
+if HERE not in sys.path:
+ sys.path.insert(0, HERE)
+
+import setup_catalog # noqa: E402
+import setup_flow # noqa: E402
+import setup_hw # noqa: E402
+
+SUPPORTED_PROTOCOLS = ("2025-06-18", "2025-03-26", "2024-11-05")
+SERVER_NAME = "colibri"
+
+PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR = (
+ -32700, -32600, -32601, -32602, -32603)
+
+INSTRUCTIONS = (
+ "colibri runs large mixture-of-experts language models locally. Typical flow: "
+ "detect_hardware, recommend_models, install (a background job: follow it with status), "
+ "start, then give the user the browser URL from the result. stop shuts the server down. "
+ "Downloads are tens to hundreds of GB: confirm the model with the user before install.")
+
+
+def _version():
+ try:
+ from version import __version__
+ return __version__
+ except ImportError:
+ return "0"
+
+
+def _schema(properties=None, required=()):
+ return {"type": "object", "properties": properties or {}, "required": list(required),
+ "additionalProperties": False}
+
+
+TOOLS = [
+ {"name": "detect_hardware", "title": "Detect hardware",
+ "description": ("RAM (total and free), free disk where models go, CPU name and features, "
+ "and GPUs: Vulkan devices with type and memory, NVIDIA cards via nvidia-smi."),
+ "inputSchema": _schema({"target_dir": {"type": "string",
+ "description": "folder whose free space to report "
+ "(default ~/colibri-models)"}})},
+ {"name": "recommend_models", "title": "Recommend models",
+ "description": ("Every downloadable model against this machine: download size, RAM needed, "
+ "whether it fits and why, with the recommended default marked."),
+ "inputSchema": _schema({"target_dir": {"type": "string"},
+ "include_unfit": {"type": "boolean", "default": False}})},
+ {"name": "install", "title": "Install a model",
+ "description": ("Build or fetch the engine (Vulkan/CUDA when a GPU is usable), download the "
+ "model with resume, write the run configuration, and by default start the "
+ "server in the background. Runs as a background job; returns at once unless "
+ "wait_seconds is set. Calling it again resumes an interrupted install."),
+ "inputSchema": _schema({
+ "model": {"type": "string", "description": "catalog id from recommend_models "
+ "(default: the recommendation)"},
+ "target_dir": {"type": "string", "description": "folder for models"},
+ "model_dir": {"type": "string", "description": "use a model already on disk"},
+ "backend": {"type": "string", "enum": ["auto", "cpu", "vulkan", "cuda"]},
+ "port": {"type": "integer", "minimum": 1, "maximum": 65535},
+ "start": {"type": "boolean", "default": True},
+ "wait_seconds": {"type": "integer", "minimum": 0, "maximum": 86400, "default": 0}})},
+ {"name": "start", "title": "Start colibri",
+ "description": "Start the configured server in the background; returns its URLs.",
+ "inputSchema": _schema({"open_browser": {"type": "boolean", "default": False},
+ "wait_seconds": {"type": "integer", "minimum": 0, "maximum": 7200,
+ "default": 0}})},
+ {"name": "stop", "title": "Stop colibri",
+ "description": "Stop the configured server and its engine.",
+ "inputSchema": _schema()},
+ {"name": "status", "title": "Status",
+ "description": ("Configured model and engine, install progress, server state (stopped, "
+ "loading, ready), browser/OpenAI/Anthropic URLs, tok/s of the last answer."),
+ "inputSchema": _schema()},
+ {"name": "logs", "title": "Logs",
+ "description": "The last lines of the server, install or build log.",
+ "inputSchema": _schema({"which": {"type": "string", "enum": ["server", "install", "build"],
+ "default": "server"},
+ "lines": {"type": "integer", "minimum": 1, "maximum": 5000,
+ "default": 100}})},
+]
+
+
+class ToolError(Exception):
+ """A tool-level failure: reported as a result with isError, not a protocol error."""
+
+
+def _log(*parts):
+ print("[colibri-mcp]", *parts, file=sys.stderr, flush=True)
+
+
+def _check_args(name, args):
+ tool = next((t for t in TOOLS if t["name"] == name), None)
+ if tool is None:
+ raise KeyError(name)
+ if not isinstance(args, dict):
+ raise ValueError("arguments must be an object")
+ props = tool["inputSchema"]["properties"]
+ for key, value in args.items():
+ if key not in props:
+ raise ValueError(f"unknown argument {key!r} for {name}")
+ kind = props[key].get("type")
+ ok = {"string": isinstance(value, str),
+ "integer": isinstance(value, int) and not isinstance(value, bool),
+ "boolean": isinstance(value, bool)}.get(kind, True)
+ if not ok:
+ raise ValueError(f"{name}.{key} must be a {kind}")
+ if "enum" in props[key] and value not in props[key]["enum"]:
+ raise ValueError(f"{name}.{key} must be one of {props[key]['enum']}")
+ if kind == "integer":
+ low, high = props[key].get("minimum"), props[key].get("maximum")
+ if (low is not None and value < low) or (high is not None and value > high):
+ raise ValueError(f"{name}.{key} is out of range")
+ return args
+
+
+# ---------------------------------------------------------------- tools
+
+
+def tool_detect_hardware(args, notify):
+ target = args.get("target_dir") or setup_flow.default_models_root()
+ report = setup_hw.detect(target)
+ report["summary"] = setup_hw.format_report(report)
+ return report
+
+
+def tool_recommend_models(args, notify):
+ target = args.get("target_dir") or setup_flow.default_models_root()
+ hw = setup_hw.detect(target, probe_gpu=False)
+ rows = setup_flow._recommend_for(hw, args.get("target_dir"))
+ models = [setup_catalog.as_dict(r) for r in rows if r["fits"] or args.get("include_unfit")]
+ default = next((m["id"] for m in models if m["recommended"]), None)
+ return {"recommended": default, "fits_means": setup_catalog.FITS_EXPLAINED,
+ "ram_total_gb": round((hw["memory"].get("total") or 0) / 1e9, 1),
+ "disk_free_gb": round((setup_hw.disk_free(target) or 0) / 1e9, 1),
+ "target_dir": target, "models": models}
+
+
+def _install_running():
+ state = setup_flow.read_state() or {}
+ if state.get("phase") in ("ready", "error", "interrupted", "done", "started", None):
+ return None
+ return state if setup_flow._pid_alive(state.get("pid")) else None
+
+
+def _coli():
+ return os.path.join(HERE, "coli")
+
+
+def tool_install(args, notify):
+ running = _install_running()
+ if running:
+ raise ToolError(f"an install is already running (pid {running.get('pid')}, phase "
+ f"{running.get('phase')}); follow it with status")
+ if args.get("model"):
+ try:
+ setup_catalog.by_id(args["model"])
+ except KeyError:
+ raise ToolError(f"unknown model {args['model']!r}; recommend_models lists the ids")
+ cmd = [sys.executable, _coli(), "setup", "--yes", "--no-browser"]
+ if args.get("model"):
+ cmd += ["--model", args["model"]]
+ if args.get("model_dir"):
+ cmd += ["--model-dir", args["model_dir"]]
+ if args.get("target_dir"):
+ cmd += ["--dir", args["target_dir"]]
+ if args.get("backend"):
+ cmd += ["--backend", args["backend"]]
+ if args.get("port"):
+ cmd += ["--port", str(args["port"])]
+ cmd += ["--background"] if args.get("start", True) else ["--no-start"]
+ log = setup_flow.log_path("install")
+ os.makedirs(os.path.dirname(log), exist_ok=True)
+ handle = open(log, "a", encoding="utf-8", errors="replace")
+ handle.write(f"\n--- install {time.strftime('%Y-%m-%d %H:%M:%S')}: {' '.join(cmd)}\n")
+ handle.flush()
+ kwargs = {"stdin": subprocess.DEVNULL, "stdout": handle, "stderr": subprocess.STDOUT,
+ "env": dict(os.environ, PYTHONUNBUFFERED="1")}
+ if sys.platform == "win32":
+ kwargs["creationflags"] = 0x00000008 | 0x00000200 | 0x08000000
+ else:
+ kwargs["start_new_session"] = True # survives the assistant closing this server
+ process = setup_flow.spawn_detached(cmd, **kwargs)
+ handle.close()
+ # The job's own pid: the child rewrites this file as it goes, with the same pid.
+ setup_flow._write_json(setup_flow.state_path(),
+ {"phase": "starting", "pid": process.pid, "updated": time.time()})
+ wait = int(args.get("wait_seconds") or 0)
+ result = {"job": {"pid": process.pid, "log": log, "command": cmd}}
+ deadline = time.time() + wait
+ while wait and time.time() < deadline:
+ code = process.poll()
+ state = setup_flow.read_state() or {}
+ if state.get("phase") == "download" and state.get("total"):
+ notify(state.get("done", 0), state["total"],
+ f"downloading {state.get('model')}: {state.get('done', 0) / 1e9:.1f} of "
+ f"{state['total'] / 1e9:.1f} GB")
+ elif state.get("phase"):
+ notify(None, None, f"install: {state['phase']}")
+ if code is not None:
+ break
+ time.sleep(1.0)
+ result["exit_code"] = process.poll()
+ result["install"] = setup_flow.read_state()
+ if result["exit_code"] not in (None, 0):
+ result["log_tail"] = setup_flow.tail_file(log, 30)
+ raise ToolError(json.dumps(result, indent=2))
+ result["next"] = ("the install continues in the background: call status to follow it"
+ if result["exit_code"] is None else "installed: call status for the URLs")
+ return result
+
+
+def _stderr_out(*parts):
+ _log(*parts)
+
+
+def tool_start(args, notify):
+ cfg = setup_flow.load_config()
+ if not cfg or not setup_flow.config_ready(cfg):
+ raise ToolError("nothing is installed yet (or the install has not finished): call install")
+ status = setup_flow.start_server(cfg, background=True,
+ open_browser=bool(args.get("open_browser")), out=_stderr_out)
+ wait = int(args.get("wait_seconds") or 0)
+ deadline = time.time() + wait
+ while wait and time.time() < deadline and status.get("state") != "ready":
+ time.sleep(2.0)
+ status = setup_flow.server_status(setup_flow.load_config() or cfg)
+ notify(None, None, f"server: {status['state']}")
+ if status["state"] == "stopped":
+ status["log_tail"] = setup_flow.tail_file(setup_flow.log_path("serve"), 30)
+ raise ToolError(json.dumps(status, indent=2))
+ return status
+
+
+def tool_stop(args, notify):
+ cfg = setup_flow.load_config()
+ if not cfg:
+ raise ToolError("nothing is configured; there is nothing to stop")
+ return setup_flow.stop_server(cfg, out=_stderr_out)
+
+
+def tool_status(args, notify):
+ return setup_flow.status_report()
+
+
+def tool_logs(args, notify):
+ which = {"server": "serve"}.get(args.get("which", "server"), args.get("which", "server"))
+ path = setup_flow.log_path(which)
+ return {"log": path, "text": setup_flow.tail_file(path, int(args.get("lines") or 100))}
+
+
+HANDLERS = {"detect_hardware": tool_detect_hardware, "recommend_models": tool_recommend_models,
+ "install": tool_install, "start": tool_start, "stop": tool_stop,
+ "status": tool_status, "logs": tool_logs}
+
+
+# ---------------------------------------------------------------- protocol
+
+
+class Server:
+ def __init__(self, out=None):
+ self.out = out or sys.stdout
+ self.lock = threading.Lock()
+ self.initialized = False
+ self.threads = []
+
+ def send(self, message):
+ line = json.dumps(message, separators=(",", ":"), ensure_ascii=False)
+ with self.lock:
+ self.out.write(line + "\n")
+ self.out.flush()
+
+ def error(self, msg_id, code, message):
+ self.send({"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}})
+
+ def result(self, msg_id, result):
+ self.send({"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+ def handle_line(self, line):
+ line = line.strip()
+ if not line:
+ return
+ try:
+ message = json.loads(line)
+ except ValueError:
+ self.error(None, PARSE_ERROR, "parse error")
+ return
+ if isinstance(message, list):
+ for item in message:
+ self.handle(item)
+ return
+ self.handle(message)
+
+ def handle(self, message):
+ if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+ self.error(message.get("id") if isinstance(message, dict) else None,
+ INVALID_REQUEST, "invalid request")
+ return
+ method = message.get("method")
+ msg_id = message.get("id")
+ is_request = "id" in message
+ if method is None:
+ return # a response to something we never asked: ignore
+ params = message.get("params") or {}
+ if not is_request:
+ return # notifications: initialized, cancelled, ...
+ if method == "initialize":
+ requested = params.get("protocolVersion") if isinstance(params, dict) else None
+ version = requested if requested in SUPPORTED_PROTOCOLS else SUPPORTED_PROTOCOLS[0]
+ self.initialized = True
+ self.result(msg_id, {"protocolVersion": version,
+ "capabilities": {"tools": {"listChanged": False}},
+ "serverInfo": {"name": SERVER_NAME, "title": "colibri",
+ "version": _version()},
+ "instructions": INSTRUCTIONS})
+ elif method == "ping":
+ self.result(msg_id, {})
+ elif method == "tools/list":
+ self.result(msg_id, {"tools": TOOLS})
+ elif method == "tools/call":
+ thread = threading.Thread(target=self.call_tool, args=(msg_id, params), daemon=True)
+ self.threads.append(thread)
+ thread.start()
+ elif method in ("resources/list", "prompts/list"):
+ self.result(msg_id, {method.split("/")[0]: []})
+ else:
+ self.error(msg_id, METHOD_NOT_FOUND, f"method not found: {method}")
+
+ def call_tool(self, msg_id, params):
+ if not isinstance(params, dict) or not isinstance(params.get("name"), str):
+ self.error(msg_id, INVALID_PARAMS, "tools/call needs a tool name")
+ return
+ name = params["name"]
+ token = (params.get("_meta") or {}).get("progressToken") if isinstance(params.get("_meta"), dict) else None
+ last = {"value": 0}
+
+ def notify(done, total, text):
+ # MCP requires progress to increase with every notification: bytes
+ # when a download reports them, else one step past the last value.
+ if token is None:
+ return
+ value = done if done is not None and done > last["value"] else last["value"] + 1
+ last["value"] = value
+ payload = {"progressToken": token, "progress": value}
+ if total and total >= value:
+ payload["total"] = total
+ if text:
+ payload["message"] = text
+ self.send({"jsonrpc": "2.0", "method": "notifications/progress", "params": payload})
+
+ try:
+ args = _check_args(name, params.get("arguments") or {})
+ except KeyError:
+ self.error(msg_id, INVALID_PARAMS, f"unknown tool: {name}")
+ return
+ except ValueError as error:
+ self.error(msg_id, INVALID_PARAMS, str(error))
+ return
+ try:
+ data = HANDLERS[name](args, notify)
+ self.result(msg_id, {"content": [{"type": "text", "text": json.dumps(data, indent=2)}],
+ "structuredContent": data if isinstance(data, dict) else {"result": data},
+ "isError": False})
+ except (ToolError, setup_flow.SetupError) as error:
+ self.result(msg_id, {"content": [{"type": "text", "text": str(error)}], "isError": True})
+ except Exception as error: # a tool bug must not take the server down
+ _log(traceback.format_exc())
+ self.result(msg_id, {"content": [{"type": "text",
+ "text": f"{type(error).__name__}: {error}"}],
+ "isError": True})
+
+ def serve(self, stream=None):
+ stream = stream or sys.stdin
+ for line in stream:
+ self.handle_line(line)
+ # stdin closed: let the calls in flight answer (a stop drains its engine)
+ # before exiting, within the minute a client gives a server to go.
+ deadline = time.time() + 60
+ for thread in self.threads:
+ thread.join(timeout=max(0.0, deadline - time.time()))
+
+
+def main():
+ if hasattr(sys.stdin, "reconfigure"):
+ try:
+ sys.stdin.reconfigure(encoding="utf-8")
+ sys.stdout.reconfigure(encoding="utf-8", newline="\n")
+ except (AttributeError, OSError, ValueError):
+ pass
+ _log(f"colibri MCP server {_version()} on stdio")
+ Server().serve()
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/c/tests/test_mcp_server.py b/c/tests/test_mcp_server.py
new file mode 100644
index 00000000..db17e1a9
--- /dev/null
+++ b/c/tests/test_mcp_server.py
@@ -0,0 +1,248 @@
+"""The MCP server: JSON-RPC 2.0 over stdio, as an AI coding assistant drives it.
+
+Round trips through the Server class (initialize, tools/list, tools/call and
+the error codes), progress notifications, and the same exchange through a real
+child process on stdin/stdout, which is how a client runs it. Tools that would
+build or download are exercised with their effects mocked; nothing here
+fetches anything.
+"""
+import io
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+C_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(C_DIR))
+import mcp_server # noqa: E402
+import setup_flow # noqa: E402
+
+
+class Exchange:
+ """A Server writing into a buffer, with helpers to read the replies."""
+
+ def __init__(self):
+ self.out = io.StringIO()
+ self.server = mcp_server.Server(out=self.out)
+
+ def send(self, message):
+ self.server.handle_line(json.dumps(message))
+
+ def wait_threads(self):
+ for thread in self.server.threads:
+ thread.join(timeout=30)
+
+ def messages(self):
+ return [json.loads(line) for line in self.out.getvalue().splitlines() if line.strip()]
+
+ def reply(self, msg_id):
+ self.wait_threads()
+ for message in self.messages():
+ if message.get("id") == msg_id and ("result" in message or "error" in message):
+ return message
+ raise AssertionError(f"no reply to {msg_id}: {self.out.getvalue()}")
+
+
+def request(msg_id, method, params=None):
+ message = {"jsonrpc": "2.0", "id": msg_id, "method": method}
+ if params is not None:
+ message["params"] = params
+ return message
+
+
+class Protocol(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ patcher = mock.patch.dict(os.environ, {"COLI_SETUP_HOME": self.tmp.name})
+ patcher.start()
+ self.addCleanup(patcher.stop)
+ self.x = Exchange()
+
+ def test_initialize_negotiates_the_version(self):
+ self.x.send(request(1, "initialize", {"protocolVersion": "2025-03-26", "capabilities": {},
+ "clientInfo": {"name": "t", "version": "1"}}))
+ result = self.x.reply(1)["result"]
+ self.assertEqual(result["protocolVersion"], "2025-03-26")
+ self.assertEqual(result["serverInfo"]["name"], "colibri")
+ self.assertIn("tools", result["capabilities"])
+ self.assertIn("install", result["instructions"])
+ self.x.send(request(2, "initialize", {"protocolVersion": "1999-01-01"}))
+ self.assertEqual(self.x.reply(2)["result"]["protocolVersion"], mcp_server.SUPPORTED_PROTOCOLS[0])
+
+ def test_notifications_get_no_reply(self):
+ self.x.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+ self.x.send({"jsonrpc": "2.0", "method": "notifications/cancelled",
+ "params": {"requestId": 3}})
+ self.assertEqual(self.x.messages(), [])
+
+ def test_ping_and_unknown_method(self):
+ self.x.send(request(1, "ping"))
+ self.assertEqual(self.x.reply(1)["result"], {})
+ self.x.send(request(2, "sampling/whatever"))
+ self.assertEqual(self.x.reply(2)["error"]["code"], mcp_server.METHOD_NOT_FOUND)
+
+ def test_parse_error_and_invalid_request(self):
+ self.x.server.handle_line("{not json")
+ self.assertEqual(self.x.messages()[-1]["error"]["code"], mcp_server.PARSE_ERROR)
+ self.x.send({"id": 5, "method": "ping"}) # no jsonrpc member
+ self.assertEqual(self.x.messages()[-1]["error"]["code"], mcp_server.INVALID_REQUEST)
+
+ def test_batch(self):
+ self.x.server.handle_line(json.dumps([request(1, "ping"), request(2, "ping")]))
+ self.assertEqual({m["id"] for m in self.x.messages()}, {1, 2})
+
+ def test_tools_list(self):
+ self.x.send(request(1, "tools/list"))
+ tools = self.x.reply(1)["result"]["tools"]
+ names = [t["name"] for t in tools]
+ self.assertEqual(names, ["detect_hardware", "recommend_models", "install", "start", "stop",
+ "status", "logs"])
+ for tool in tools:
+ self.assertTrue(tool["description"])
+ self.assertEqual(tool["inputSchema"]["type"], "object")
+ json.dumps(tool)
+
+ def test_status_before_setup(self):
+ self.x.send(request(1, "tools/call", {"name": "status", "arguments": {}}))
+ result = self.x.reply(1)["result"]
+ self.assertFalse(result["isError"])
+ self.assertEqual(result["structuredContent"]["configured"], False)
+ self.assertEqual(json.loads(result["content"][0]["text"])["configured"], False)
+
+ def test_tool_errors_are_results_not_protocol_errors(self):
+ self.x.send(request(1, "tools/call", {"name": "start", "arguments": {}}))
+ result = self.x.reply(1)["result"]
+ self.assertTrue(result["isError"])
+ self.assertIn("install", result["content"][0]["text"])
+
+ def test_argument_validation(self):
+ cases = [("nope", {}), ("logs", {"lines": "ten"}), ("logs", {"which": "kernel"}),
+ ("logs", {"lines": 0}), ("status", {"extra": 1}), ("install", {"port": True})]
+ for number, (name, args) in enumerate(cases, 1):
+ with self.subTest(name=name, args=args):
+ self.x.send(request(number, "tools/call", {"name": name, "arguments": args}))
+ self.assertEqual(self.x.reply(number)["error"]["code"], mcp_server.INVALID_PARAMS)
+
+ def test_recommend_models(self):
+ fake_hw = {"os": {"machine": "x86_64"}, "memory": {"total": 27 * 10**9}}
+ with mock.patch.object(mcp_server.setup_hw, "detect", return_value=fake_hw), \
+ mock.patch.object(mcp_server.setup_hw, "disk_free", return_value=800 * 10**9), \
+ mock.patch.object(setup_flow.setup_hw, "disk_free", return_value=800 * 10**9):
+ self.x.send(request(1, "tools/call", {"name": "recommend_models", "arguments": {}}))
+ data = self.x.reply(1)["result"]["structuredContent"]
+ self.assertEqual(data["recommended"], "qwen36-35b")
+ self.assertTrue(all(m["fits"] for m in data["models"]))
+ self.assertIn("dense part", data["fits_means"])
+
+ def test_install_starts_a_background_job(self):
+ class FakeProcess:
+ pid = 4242
+
+ def poll(self):
+ return None
+
+ with mock.patch.object(mcp_server.setup_flow, "spawn_detached",
+ return_value=FakeProcess()) as spawn:
+ self.x.send(request(1, "tools/call", {"name": "install", "arguments": {
+ "model": "qwen3-coder-30b", "backend": "cpu", "port": 8100}}))
+ result = self.x.reply(1)["result"]
+ self.assertFalse(result["isError"], result)
+ command = spawn.call_args[0][0]
+ self.assertEqual(command[1:4], [str(C_DIR / "coli"), "setup", "--yes"])
+ for piece in ("--model", "qwen3-coder-30b", "--backend", "cpu", "--port", "8100",
+ "--background", "--no-browser"):
+ self.assertIn(piece, command)
+ self.assertEqual(result["structuredContent"]["job"]["pid"], 4242)
+ self.assertEqual(setup_flow.read_state()["pid"], 4242)
+
+ def test_install_refuses_unknown_models_and_a_second_job(self):
+ self.x.send(request(1, "tools/call", {"name": "install", "arguments": {"model": "gpt-9"}}))
+ self.assertTrue(self.x.reply(1)["result"]["isError"])
+ setup_flow._write_json(setup_flow.state_path(), {"phase": "download", "pid": os.getpid()})
+ self.x.send(request(2, "tools/call", {"name": "install", "arguments": {}}))
+ result = self.x.reply(2)["result"]
+ self.assertTrue(result["isError"])
+ self.assertIn("already running", result["content"][0]["text"])
+
+ def test_progress_notifications_increase(self):
+ def handler(args, notify):
+ notify(None, None, "build")
+ notify(500, 1000, "half")
+ notify(400, 1000, "a smaller byte count must not go backwards")
+ notify(None, None, "ready")
+ return {"ok": True}
+
+ with mock.patch.dict(mcp_server.HANDLERS, {"status": handler}):
+ self.x.send(request(9, "tools/call", {"name": "status", "arguments": {},
+ "_meta": {"progressToken": "tok"}}))
+ self.x.reply(9)
+ progress = [m["params"] for m in self.x.messages()
+ if m.get("method") == "notifications/progress"]
+ values = [p["progress"] for p in progress]
+ self.assertEqual(len(values), 4)
+ self.assertEqual(values, sorted(set(values)))
+ self.assertTrue(all(p["progressToken"] == "tok" for p in progress))
+ self.assertEqual(progress[1]["total"], 1000)
+
+ def test_no_token_no_notifications(self):
+ def handler(args, notify):
+ notify(1, 2, "x")
+ return {}
+
+ with mock.patch.dict(mcp_server.HANDLERS, {"status": handler}):
+ self.x.send(request(1, "tools/call", {"name": "status", "arguments": {}}))
+ self.x.reply(1)
+ self.assertFalse(any(m.get("method") for m in self.x.messages()))
+
+ def test_logs(self):
+ log = setup_flow.log_path("serve")
+ os.makedirs(os.path.dirname(log))
+ Path(log).write_text("\n".join(f"line {i}" for i in range(50)))
+ self.x.send(request(1, "tools/call", {"name": "logs", "arguments": {"lines": 3}}))
+ data = self.x.reply(1)["result"]["structuredContent"]
+ self.assertEqual(data["text"], "line 47\nline 48\nline 49")
+
+ def test_a_crashing_tool_does_not_take_the_server_down(self):
+ with mock.patch.dict(mcp_server.HANDLERS, {"status": lambda a, n: 1 / 0}), \
+ mock.patch.object(mcp_server, "_log") as logged:
+ self.x.send(request(1, "tools/call", {"name": "status", "arguments": {}}))
+ result = self.x.reply(1)["result"]
+ self.assertTrue(result["isError"])
+ self.assertIn("ZeroDivisionError", result["content"][0]["text"])
+ self.assertIn("ZeroDivisionError", logged.call_args[0][0]) # the traceback goes to stderr
+ self.x.send(request(2, "ping"))
+ self.assertEqual(self.x.reply(2)["result"], {})
+
+
+class StdioRoundTrip(unittest.TestCase):
+ """The way a client runs it: a child process, one JSON message per line."""
+
+ def test_over_stdin_and_stdout(self):
+ with tempfile.TemporaryDirectory() as home:
+ env = dict(os.environ, COLI_SETUP_HOME=home)
+ process = subprocess.Popen([sys.executable, str(C_DIR / "coli"), "mcp"],
+ stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, text=True, env=env)
+ lines = [request(1, "initialize", {"protocolVersion": "2025-06-18", "capabilities": {},
+ "clientInfo": {"name": "test", "version": "0"}}),
+ {"jsonrpc": "2.0", "method": "notifications/initialized"},
+ request(2, "tools/list"),
+ request(3, "tools/call", {"name": "status", "arguments": {}})]
+ out, err = process.communicate("\n".join(json.dumps(m) for m in lines) + "\n",
+ timeout=60)
+ replies = [json.loads(line) for line in out.splitlines()]
+ self.assertEqual([r["id"] for r in replies], [1, 2, 3]) # stdout carries JSON only
+ self.assertEqual(replies[0]["result"]["serverInfo"]["name"], "colibri")
+ self.assertEqual(len(replies[1]["result"]["tools"]), 7)
+ self.assertFalse(replies[2]["result"]["isError"])
+ self.assertIn("colibri MCP server", err) # diagnostics on stderr
+
+
+if __name__ == "__main__":
+ unittest.main()