Skip to main content
Glama

System on an Agent: plugin edition

Published by Earthenware Computer. This is the plugin / MCP-server edition of System on an Agent. It carries the full history of that repository plus a stdio MCP server, a Cursor plugin manifest, and MCP Registry metadata, so it can be submitted to the xAI plugin marketplace.

A system on a chip puts a CPU, memory, I/O, and a bus on one piece of silicon. A system on an agent puts the same parts into one agent:

System on a Chip

System on an Agent

CPU

Planner (the processor)

Memory

Memory and skills (storage)

I/O

Connectors (input and output)

On-chip bus

Bus / router

The core is only those four parts. Optional add-ons plug in later through a manifest and hook interface, without changing the core.

flowchart TB
  subgraph chip["System on a Chip"]
    direction LR
    c_cpu["CPU"]
    c_mem["Memory"]
    c_io["I/O"]
    c_bus["On-chip bus"]
  end
  subgraph agent["System on an Agent"]
    direction LR
    a_cpu["Planner<br/>processor"]
    a_mem["Memory + Skills<br/>storage"]
    a_io["Connectors<br/>input / output"]
    a_bus["Bus / Router"]
  end
  c_cpu -.-> a_cpu
  c_mem -.-> a_mem
  c_io -.-> a_io
  c_bus -.-> a_bus

Core

  • Planner. Takes a goal, builds a plan, and runs it step by step. The default planner is deterministic and rule-based; no language model is required. An optional LLMProvider interface can be attached later. If the model fails to return a valid plan, the rule-based planner is the fallback.

  • Memory and skills. Working memory holds short-lived values for the current run. Long-term memory stores facts (optionally persisted as JSON). The skill library is a set of reusable named procedures the planner can run.

  • Connectors. A pluggable I/O surface. This repository ships a local file connector and an echo (mock) connector.

  • Bus / router. Routes messages between the planner, memory, skills, and connectors, and fires add-on hooks around each step.

Related MCP server: mcp-context-card

Quickstart

Requires Python 3.10 or newer.

python -m pip install -e ".[dev]"
soa skills list
soa connectors list
soa run "echo hello from system on an agent"
pytest

soa run prints the goal, the plan, and the output. Add --json for a machine-readable report. Built-in goal forms include:

  • echo hello / say hello — send text through the echo connector

  • remember the sky is blue — store a fact

  • recall sky — look up facts

  • read path/to/file and write hello to path/to/file — file connector

  • list skills / list connectors

  • Join steps with then: echo hi then remember hi was said

Use as an MCP server

soa mcp (or system-on-an-agent mcp) serves the system over the Model Context Protocol on stdio. The server is built into the package: it needs no extra dependencies and opens no network sockets.

Tool

What it does

plan_goal

Plan a goal with the rule-based planner and return the steps without running them.

run_goal

Plan and run a goal on the bus; returns the plan, each step result, and the output.

memory_remember

Store a fact (with optional tags) in long-term memory.

memory_recall

Look up facts by substring; an empty query returns all facts.

list_skills

List the skill library with descriptions and parameters.

run_skill

Run one named skill through the bus, e.g. echo with {"text": "hi"}.

list_connectors

List the registered connectors (echo, file).

Options go before mcp:

  • --file-root DIR confines the file connector to DIR (default: the working directory). Paths that escape it fail.

  • --memory-file PATH persists long-term memory as JSON at PATH (default: in memory for the session).

  • --addon PATH loads an optional add-on, as with soa run.

Connect it to an MCP client

Run it straight from GitHub with uv:

{
  "mcpServers": {
    "system-on-an-agent": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin",
        "system-on-an-agent",
        "mcp"
      ]
    }
  }
}

Or install it into a Python 3.10+ environment and point the client at the script:

python -m pip install "git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin"
{
  "mcpServers": {
    "system-on-an-agent": {
      "command": "system-on-an-agent",
      "args": ["--file-root", "/path/to/workdir", "--memory-file", "/path/to/memory.json", "mcp"]
    }
  }
}

This repository is also a Cursor plugin: .cursor-plugin/plugin.json points at mcp.json, the skill, and the logo. server.json describes the server in the MCP Registry format.

Test it locally

python -m pip install -e ".[dev]"   # adds pytest, ruff, and the official MCP Python SDK
ruff check src tests
pytest                              # tests/test_mcp_client.py starts the server and calls every tool

Submitting to the xAI marketplace

The Submit a plugin form lists plugins for Grok Bot, Cursor, and Grok (coming soon). It takes an MCP server URL or a public GitHub repository, which this repository is (submit this plugin repository, not the upstream one). The form does not publish a manifest spec, so this repo follows the Cursor plugin format (.cursor-plugin/plugin.json + mcp.json) and MCP Registry server.json conventions. That is an assumption to confirm during review.

Done in the repo:

  • Working stdio MCP server with seven tools, tested through the official MCP client

  • Cursor plugin manifest, mcp.json, skill, and a square logo (assets/logo.svg, assets/logo.png)

  • server.json for the MCP Registry

  • MIT license, no secrets or required environment variables

Needs a person:

  • First and last name of the submitter

  • Work email. The form asks for a work email, so a personal Gmail may not pass review.

  • Organization name (Earthenware Computer) and a unique lowercase organization handle (no spaces), e.g. earthenware-computer

  • Website URL (optional), e.g. https://fitzyracing1.github.io/system-on-an-agent/

  • Logotype URL: a 1:1 SVG or PNG with a background plate. https://raw.githubusercontent.com/Earthenware-Computer/system-on-an-agent-plugin/main/assets/logo.png

  • Pick where to be listed: Grok Bot, Cursor, and/or Grok (coming soon)

  • MCP Server URL or Public GitHub Repository: https://github.com/Earthenware-Computer/system-on-an-agent-plugin

  • Brief description and testing instructions (for example: add the mcp.json entry above, call list_skills, then run_goal with echo hello then remember hello was said)

  • Test the plugin locally and in-app, then tick the box confirming it works

  • Read and accept the Publisher Terms

  • Optional: publish system-on-an-agent to PyPI and then server.json to the MCP Registry (mcp-publisher), which needs PyPI and GitHub sign-in

Optional add-ons

Add-ons are not part of the core. They load from a Python file or a directory (containing soa_addon.py or addon.py) and declare a manifest plus the hooks they implement:

  • before_plan(plan, context)

  • after_plan(plan, report, context)

  • before_step(step, context)

  • after_step(step, result, context)

  • on_error(step, error, context)

soa --addon path/to/addon.py run "echo hello"

The module must expose an Addon class, a create_addon() factory, or an addon instance. See docs/addons.md for the interface and for reserved future add-ons (heatgate and the Lex loop), which are documented only as placeholders and are not implemented here.

License

MIT. Copyright (c) 2026 Joshua Almeida.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An agent-capable MCP server with terminal access, filesystem control, and persistent memory. It includes sandboxing, access control, activity logging, and a file-backed memory store for context across conversations.
      32 PyPI
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An all-in-one MCP server that enables AI agents with local system capabilities like filesystem navigation, command execution, desktop automation, and a continuity memory suite for persistent cross-session project context.
      37
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides a drop-in MCP memory server over stdio using a local SQLite store, enabling agents to store, search, and audit memory with provenance, scoped access, and contradiction tracking without requiring API keys, LLMs, or embedding providers.
      1,147 npm
      17
      Apache 2.0