{"id":50140381,"url":"https://github.com/farchanjo/substrate","last_synced_at":"2026-05-24T01:02:15.084Z","repository":{"id":359615169,"uuid":"1246825479","full_name":"farchanjo/substrate","owner":"farchanjo","description":"Model Context Protocol (MCP) server in Rust 1.95 exposing POSIX baseutils-equivalent OS management to LLM agents over STDIO. 37 tools across 7 bounded contexts. Spec-as-source-of-truth (MADR/CUE/Gherkin/Rego/TLA+).","archived":false,"fork":false,"pushed_at":"2026-05-22T20:39:25.000Z","size":871,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T20:44:32.711Z","etag":null,"topics":["anthropic","archive","async","baseutils","claude","ddd","filesystem","hexagonal-architecture","llm-tools","madr","mcp","model-context-protocol","posix","process-management","rust","rust-2024","simd","spec-as-source-of-truth","stdio-transport","tokio"],"latest_commit_sha":null,"homepage":"https://github.com/farchanjo/substrate","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/farchanjo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T15:42:07.000Z","updated_at":"2026-05-22T20:39:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/farchanjo/substrate","commit_stats":null,"previous_names":["farchanjo/substrate"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/farchanjo/substrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Fsubstrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Fsubstrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Fsubstrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Fsubstrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/farchanjo","download_url":"https://codeload.github.com/farchanjo/substrate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Fsubstrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33417489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","archive","async","baseutils","claude","ddd","filesystem","hexagonal-architecture","llm-tools","madr","mcp","model-context-protocol","posix","process-management","rust","rust-2024","simd","spec-as-source-of-truth","stdio-transport","tokio"],"created_at":"2026-05-24T01:02:14.291Z","updated_at":"2026-05-24T01:02:15.071Z","avatar_url":"https://github.com/farchanjo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# substrate\n\nModel Context Protocol (MCP) server in Rust 1.95 exposing POSIX baseutils-equivalent\nOS management to LLM agents over STDIO. Seven bounded contexts: filesystem-query,\nfilesystem-mutation, process, system-info, text-processing, archive, job.\n\n## Quick Start\n\n### Prerequisites\n\n- Rust 1.95+ (`rustup install 1.95 \u0026\u0026 rustup default 1.95`).\n- macOS 11+ or Linux kernel 5.6+ for tier-1 PathJail (otherwise userspace tier\n  with WARN).\n- `mise` (optional, manages Rust + cargo tools automatically).\n\n### Build\n\n```bash\nmise trust \u0026\u0026 mise install   # if mise is available\ncargo build --workspace --release\n```\n\nThe release binary lands at `target/release/substrate-mcp-server`.\n\n### Run\n\nCreate `substrate.toml` at the project root or `~/.config/substrate/config.toml`:\n\n```toml\n[policy]\nroots = [\"/path/to/sandbox\"]\n\n[logging]\nlevel = \"info\"\ntarget = \"stderr\"\n\n[security]\nrefuse_degraded_jail = true\n\n[timeouts]\nglobal_default_seconds = 30\nshutdown_drain_secs = 5\n```\n\nRun the server (it speaks JSON-RPC 2.0 over STDIO):\n\n```bash\n./target/release/substrate-mcp-server\n```\n\n### Example interaction\n\n```bash\nprintf '%s\\n%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":1,\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0.0.1\"}}}' \\\n  '{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"id\":2,\"params\":{\"name\":\"sys_hostname\",\"arguments\":{}}}' \\\n| ./target/release/substrate-mcp-server\n```\n\n## System Overview\n\nThe following flowchart shows the principal actors and their relationships at the system boundary.\n\n```mermaid\nflowchart LR\n    OP[Operator / Human] --\u003e|elicitation forms| HOST[MCP Host\\ne.g. Claude Desktop]\n    AGENT[LLM Agent] --\u003e|MCP JSON-RPC| HOST\n    HOST --\u003e|STDIO stdin/stdout| SRV[substrate\\nMCP server]\n    SRV --\u003e|syscalls| FS[Local Filesystem]\n    SRV --\u003e|procfs / sysctl| OS[OS / Kernel]\n```\n\nThe following sequence diagram shows the smoke-test interaction from connection through a tool call.\n\nNote: tool names use `_` as separator (e.g. `sys_hostname`), not `.`.\n\n```mermaid\nsequenceDiagram\n    participant C as MCP Client\n    participant S as substrate server\n    C-\u003e\u003eS: initialize (protocolVersion, clientInfo)\n    S--\u003e\u003eC: InitializeResult (capabilities, serverInfo)\n    C-\u003e\u003eS: tools/list\n    S--\u003e\u003eC: ListToolsResult (tool cards array)\n    C-\u003e\u003eS: tools/call (sys_hostname, args={})\n    S--\u003e\u003eC: CallToolResult (content text + structuredContent)\n```\n\n## Architecture\n\nThis repository uses spec-as-source-of-truth. All architectural decisions live\nunder `docs/arch/` as MADR 4.0 ADRs, CUE schemas, Gherkin features, Rego policies,\nStructurizr DSL, OpenSLO definitions, AsyncAPI spec, and a TLA+ formal model.\n\nRead in order:\n\n1. [Architecture Overview](docs/arch/README.md) — entry point for the spec\n2. [Glossary](docs/arch/glossary.md) — ubiquitous-language vocabulary\n3. [ADR-0002](docs/arch/adr/0002-bounded-contexts.md) — strategic DDD and the seven bounded contexts (filesystem-query, filesystem-mutation, process, system-info, text-processing, archive, job)\n4. [ADR-0040](docs/arch/adr/0040-async-job-control-plane.md) — async job control-plane (Push/Pull dual channel)\n\n## Validation\n\n```bash\nspec validate --lane full      # 13 spec validators\ncargo clippy --locked --workspace --all-targets -- -D warnings\ncargo nextest run --locked --workspace --no-fail-fast\n```\n\n## TLA+ formal verification\n\nA `JobRegistry.tla` model lives under `docs/arch/`. To enable the `run_tlc`\nvalidator:\n\n```bash\n# Download tla2tools.jar once (see tools/README.md)\ncurl -L -o tools/tla2tools.jar \\\n  https://github.com/tlaplus/tlaplus/releases/latest/download/tla2tools.jar\n\n# Then run the spec full lane -- TLC will be invoked automatically\nspec validate --lane full\n```\n\nThe `TLA2TOOLS_JAR` environment variable is auto-set by `mise` when\n`tools/tla2tools.jar` is present. See `tools/README.md` for details.\n\n## License\n\nDual-licensed under MIT OR Apache-2.0. See `LICENSE-MIT` and `LICENSE-APACHE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarchanjo%2Fsubstrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarchanjo%2Fsubstrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarchanjo%2Fsubstrate/lists"}