Skip to content

lukacf/botus-1-2-3

v0.1.0MIT OR Apache-2.0

Persistent agent spreadsheets through two MCP tools. Recalculate like it is 1989.

GitHubOpen Website

Botus 1-2-3

Botus 1-2-3: a beige computer, boxed software and floppy disks, with the slogan Recalculate like it is 1989.

Recalculate like it is 1989.

A spreadsheet workspace for agents that have better things to do than ask for shell access. The package name is botus-1-2-3; Rust imports use botus_1_2_3.

Botus takes its cell addresses and ranges from Lotus 1-2-3, with Unicode text and automatic recalculation. See SPEC.md for the implementation contract and acceptance tests. The little green spreadsheet manual covers values, formulas, copying, sorting and bounded reads.

Status and installation

Botus is available from source under MIT OR Apache-2.0, at your option. It is not published to a package registry. The default Rust build provides the standalone spreadsheet engine; the optional mcp feature adds the MCP server and host integration.

The validated host integration uses Meerkat 0.8.52 and the exact MobKit revision in Cargo.toml. Use that same dependency set in the host. The upstream storage and MCP support also ships in Meerkat Meta 0.9, but this Botus package has not yet been qualified against that version.

For installation and host setup, follow MCP.md. Agents need a configured host for persistent storage and authenticated access; the skill and executable alone do not provide those services.

The companion agent skill contains the complete functional reference, with separate chapters for read, apply, cell operations, formulas, access control, and limits and errors. Agents retrieve one complete chapter through the existing read tool, without shell access: botus_read {"action":"help","topic":"read"} or botus_read {"action":"help","topic":"apply"}. The other topics are operations, formulas, access, and limits. All chapters travel with the skill and are embedded in the host-side tool implementation from those same files. Help still requires an active host binding and authenticated caller; installing the skill alone does not provide tool access.

Package assets

plugin.json and mcp.json use the Agent Plugins 1.0.0 format. The MCP entry point is botus-1-2-3 mcp. The optional mcp Cargo feature builds that executable; the default engine build remains independent of the runtime. The MCP host guide explains composition, persistence and caller authority. The transport and caller-context contract specifies how each tool call is bound to its authenticated runtime context.

Copy the manifests and complete skill to a new plugin directory with:

python3 scripts/install-plugin-assets /your/plugin-directory/botus-1-2-3

This copies public package assets only. The executable must also be installed on the host's PATH. The manifest does not supply a storage backend or caller authority: the host must bind its MobKit services and trusted per-call MCP context. A skill describes how to use the tools; installing it does not activate them. Host setup and wire-level acceptance remain separate from asset installation.

Three easy steps

  1. Put structured data in a workbook.
  2. Calculate, filter and share it with authorized agents.
  3. Persist through MobKit.

Two agent tools, botus_read and botus_apply, serve the whole workspace. Bulk operations and bounded responses keep tool calls and context use small.

A cell of one's own

Workbooks default to private ownership by the creating agent's host identity. Forks inherit permitted data access to the same workbook; they do not receive ownership. Owners can explicitly share with children, other agents or a mob. Realm ownership does not imply that every agent can read the document.

MobKit supplies persistence and enforces access through its document store. The engine itself remains independent of the agent runtime.

Compatibility

The interaction model is inspired by Lotus 1-2-3 Release 2.2. Workbooks use versioned JSON. WK1 and Lotus binary compatibility are not supported.

Native bundle or MCP document-binding activation opts the host's local continuity store into schema v3 identity history. Earlier binaries which support only v1/v2 then refuse that database. Ordinary opens and head-only migration do not opt in. See the native guide for the compatibility boundary.

Development

Use make check, make test, make lint and make fmt. Build caches stay outside the repository through scripts/repo-cargo.

The sparse engine, formula evaluator, compact native adapter and tests are implemented here. Start with the runnable beige budget or the native integration guide. The engine review records its findings and fixes; the manual describes supported operations and limits.

The pinned host integration has passed installed-relay acceptance covering parent, child, fork, restart and access revocation behavior. This is separate from the pure-engine test suite and does not establish compatibility with other runtime versions. WK1, macros and protected exports remain deferred.

See CONTRIBUTING.md for development and verification.

License

Choose either the MIT license or Apache License 2.0. Contributions are accepted under the same dual license.