Skip to content
Back to search

system-on-an-agent-plugin

Plugin / MCP-server edition of System on an Agent, published by Earthenware Computer. Planner, memory, skills, and connectors as a local stdio MCP server. MIT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/earthenware-computer--system-on-an-agent-plugin/badge.svg)](/listings/earthenware-computer--system-on-an-agent-plugin)

HTML

<a href="/listings/earthenware-computer--system-on-an-agent-plugin"><img src="/api/listings/earthenware-computer--system-on-an-agent-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 178 lines
  1. # System on an Agent: plugin edition
  2. <!-- mcp-name: io.github.earthenware-computer/system-on-an-agent-plugin -->
  3. > Published by **Earthenware Computer**. This is the **plugin / MCP-server edition** of [System on an Agent](https://github.com/fitzyracing1/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.
  4. 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:
  5. | System on a Chip | System on an Agent |
  6. | --- | --- |
  7. | CPU | Planner (the processor) |
  8. | Memory | Memory and skills (storage) |
  9. | I/O | Connectors (input and output) |
  10. | On-chip bus | Bus / router |
  11. The core is only those four parts. Optional add-ons plug in later through a manifest and hook interface, without changing the core.
  12. ```mermaid
  13. flowchart TB
  14. subgraph chip["System on a Chip"]
  15. direction LR
  16. c_cpu["CPU"]
  17. c_mem["Memory"]
  18. c_io["I/O"]
  19. c_bus["On-chip bus"]
  20. end
  21. subgraph agent["System on an Agent"]
  22. direction LR
  23. a_cpu["Planner<br/>processor"]
  24. a_mem["Memory + Skills<br/>storage"]
  25. a_io["Connectors<br/>input / output"]
  26. a_bus["Bus / Router"]
  27. end
  28. c_cpu -.-> a_cpu
  29. c_mem -.-> a_mem
  30. c_io -.-> a_io
  31. c_bus -.-> a_bus
  32. ```
  33. ## Core
  34. - **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.
  35. - **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.
  36. - **Connectors.** A pluggable I/O surface. This repository ships a local file connector and an echo (mock) connector.
  37. - **Bus / router.** Routes messages between the planner, memory, skills, and connectors, and fires add-on hooks around each step.
  38. ## Quickstart
  39. Requires Python 3.10 or newer.
  40. ```bash
  41. python -m pip install -e ".[dev]"
  42. soa skills list
  43. soa connectors list
  44. soa run "echo hello from system on an agent"
  45. pytest
  46. ```
  47. `soa run` prints the goal, the plan, and the output. Add `--json` for a machine-readable report. Built-in goal forms include:
  48. - `echo hello` / `say hello` — send text through the echo connector
  49. - `remember the sky is blue` — store a fact
  50. - `recall sky` — look up facts
  51. - `read path/to/file` and `write hello to path/to/file` — file connector
  52. - `list skills` / `list connectors`
  53. - Join steps with `then`: `echo hi then remember hi was said`
  54. ## Use as an MCP server
  55. `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.
  56. | Tool | What it does |
  57. | --- | --- |
  58. | `plan_goal` | Plan a goal with the rule-based planner and return the steps without running them. |
  59. | `run_goal` | Plan and run a goal on the bus; returns the plan, each step result, and the output. |
  60. | `memory_remember` | Store a fact (with optional tags) in long-term memory. |
  61. | `memory_recall` | Look up facts by substring; an empty query returns all facts. |
  62. | `list_skills` | List the skill library with descriptions and parameters. |
  63. | `run_skill` | Run one named skill through the bus, e.g. `echo` with `{"text": "hi"}`. |
  64. | `list_connectors` | List the registered connectors (`echo`, `file`). |
  65. Options go before `mcp`:
  66. - `--file-root DIR` confines the file connector to `DIR` (default: the working directory). Paths that escape it fail.
  67. - `--memory-file PATH` persists long-term memory as JSON at `PATH` (default: in memory for the session).
  68. - `--addon PATH` loads an optional add-on, as with `soa run`.
  69. ### Connect it to an MCP client
  70. Run it straight from GitHub with [uv](https://docs.astral.sh/uv/):
  71. ```json
  72. {
  73. "mcpServers": {
  74. "system-on-an-agent": {
  75. "command": "uvx",
  76. "args": [
  77. "--from",
  78. "git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin",
  79. "system-on-an-agent",
  80. "mcp"
  81. ]
  82. }
  83. }
  84. }
  85. ```
  86. Or install it into a Python 3.10+ environment and point the client at the script:
  87. ```bash
  88. python -m pip install "git+https://github.com/Earthenware-Computer/system-on-an-agent-plugin"
  89. ```
  90. ```json
  91. {
  92. "mcpServers": {
  93. "system-on-an-agent": {
  94. "command": "system-on-an-agent",
  95. "args": ["--file-root", "/path/to/workdir", "--memory-file", "/path/to/memory.json", "mcp"]
  96. }
  97. }
  98. }
  99. ```
  100. This repository is also a Cursor plugin: [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) points at [`mcp.json`](mcp.json), the [skill](skills/system-on-an-agent/SKILL.md), and the [logo](assets/logo.svg). [`server.json`](server.json) describes the server in the [MCP Registry](https://github.com/modelcontextprotocol/registry) format.
  101. ### Test it locally
  102. ```bash
  103. python -m pip install -e ".[dev]" # adds pytest, ruff, and the official MCP Python SDK
  104. ruff check src tests
  105. pytest # tests/test_mcp_client.py starts the server and calls every tool
  106. ```
  107. ## Submitting to the xAI marketplace
  108. The [Submit a plugin](https://x.ai/bot/marketplace/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.
  109. Done in the repo:
  110. - [x] Working stdio MCP server with seven tools, tested through the official MCP client
  111. - [x] Cursor plugin manifest, `mcp.json`, skill, and a square logo (`assets/logo.svg`, `assets/logo.png`)
  112. - [x] `server.json` for the MCP Registry
  113. - [x] MIT license, no secrets or required environment variables
  114. Needs a person:
  115. - [ ] **First and last name** of the submitter
  116. - [ ] **Work email.** The form asks for a work email, so a personal Gmail may not pass review.
  117. - [ ] **Organization name** (Earthenware Computer) and a unique lowercase **organization handle** (no spaces), e.g. `earthenware-computer`
  118. - [ ] **Website URL** (optional), e.g. `https://fitzyracing1.github.io/system-on-an-agent/`
  119. - [ ] **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`
  120. - [ ] Pick where to be listed: **Grok Bot**, **Cursor**, and/or **Grok** (coming soon)
  121. - [ ] **MCP Server URL or Public GitHub Repository**: `https://github.com/Earthenware-Computer/system-on-an-agent-plugin`
  122. - [ ] **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`)
  123. - [ ] Test the plugin locally and in-app, then tick the box confirming it works
  124. - [ ] Read and accept the [Publisher Terms](https://cursor.com/marketplace-publisher-terms)
  125. - [ ] 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
  126. ## Optional add-ons
  127. 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:
  128. - `before_plan(plan, context)`
  129. - `after_plan(plan, report, context)`
  130. - `before_step(step, context)`
  131. - `after_step(step, result, context)`
  132. - `on_error(step, error, context)`
  133. ```bash
  134. soa --addon path/to/addon.py run "echo hello"
  135. ```
  136. The module must expose an `Addon` class, a `create_addon()` factory, or an `addon` instance. See [docs/addons.md](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.
  137. ## License
  138. MIT. Copyright (c) 2026 Joshua Almeida.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.