Computer Board

What Computer Board MCP server does

Computer Board maintains a JSON-configured inventory of machines and software. Each entry can include a name, host, description, usage instructions, tips, dependencies, enabled state, and health-check definitions. The service exposes that information as read-only agent tools and can also serve a read-only web page when built web assets are present.

The Computer Board MCP server is intended for questions such as which machines are currently available, how a piece of software is accessed, and whether a configured resource is healthy. It does not execute agent-requested business actions, proxy remote calls, provide SSH or port forwarding, or modify the inventory through MCP.

How it works

At startup, the service reads ~/.computer/config.json, unless COMPUTER_BOARD_CONFIG points to another file. It periodically runs configured checks. A local check marks the Board host as available, while a bash check runs a fixed command on the Board host; remote checks can be expressed as one-shot commands such as ssh host <command>. Successful checks are healthy, failed checks become degraded or unhealthy according to the configured failure threshold, and unchecked resources remain unknown.

The Computer Board MCP server keeps health results and its BM25 machine search index in memory. Queries do not trigger a new health check. Configuration changes are watched and reloaded automatically, including machine data, defaults, and search content. Invalid changes leave the last valid configuration active until the file is corrected.

HTTP MCP uses Streamable HTTP, JSON responses, no session, and no authentication. The default endpoint is http://127.0.0.1:3000/mcp. A separate pi extension uses the same four tools and can start or reuse a background service instance.

Setup and configuration

Node.js 22 or newer is required. Install the package globally, create a sample configuration, edit it, validate it, and start the service:

npm install -g @black942026/computer-board
computer-board init
computer-board validate
computer-board

computer-board ensure starts or reuses a background instance, while computer-board stop stops it. The configured server.host, server.port, and server.path control the HTTP MCP address. Health-check defaults include interval, timeout, failure threshold, and concurrency; individual checks can override these values.

The service has no login or permission controls and should remain on a loopback address unless additional protection is provided externally. Do not place secrets in descriptions, instructions, tips, dependencies, or check arguments because these values can be returned to agents.

Tools and capabilities

The Computer Board MCP server provides these read-only tools:

• list_machines: Lists machine names, hosts, and software names. showAll includes status values.
• search_machine: Searches machine id, name, and host with BM25 ranking. It can include unhealthy or disabled entries and accepts a result limit.
• get_machine: Returns one machine's descriptions, instructions, dependencies, health checks, status information, and software index.
• get_software: Returns software access details, notes, dependencies, observed version, health checks, and its host machine.

A typical lookup lists or searches machines first, then uses the returned identifier with a detail tool. Results omit unset fields rather than using null values. Errors can identify invalid arguments, missing resources, ambiguous matches, or internal startup failures.

Limitations and notes

By default, lists and searches include only machines whose configured health checks currently pass. showAll=true returns all matching resources with their statuses, and resources hidden from default lists can still be retrieved by ID. Health results are lost on restart and are recalculated afterward.

Exact host lookups require the complete configured value, including account and port. Search is limited to machine IDs, names, and hosts; it does not search descriptions, instructions, or software fields. Duplicate software names or hosts can produce an ambiguity error. Changing the listening host or port requires stopping and restarting the service, while most other configuration changes take effect during hot reload.