{"id":48898944,"url":"https://github.com/amarbel-llc/moxy","last_synced_at":"2026-06-07T01:01:45.554Z","repository":{"id":345495904,"uuid":"1181635981","full_name":"amarbel-llc/moxy","owner":"amarbel-llc","description":"MCP proxy aggregating child servers behind one connection, with result caching, progressive disclosure, composable result URIs, a declarative micro-MCP framework, and per-tool permission policy","archived":false,"fork":false,"pushed_at":"2026-05-31T01:26:45.000Z","size":3056,"stargazers_count":0,"open_issues_count":104,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-31T03:07:07.051Z","etag":null,"topics":["ai-tools","claude-code","cli","declarative-tools","golang","mcp","model-context-protocol","proxy"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amarbel-llc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-03-14T12:17:35.000Z","updated_at":"2026-05-31T01:26:49.000Z","dependencies_parsed_at":"2026-05-31T03:03:21.440Z","dependency_job_id":null,"html_url":"https://github.com/amarbel-llc/moxy","commit_stats":null,"previous_names":["amarbel-llc/moxy"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/amarbel-llc/moxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarbel-llc%2Fmoxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarbel-llc%2Fmoxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarbel-llc%2Fmoxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarbel-llc%2Fmoxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amarbel-llc","download_url":"https://codeload.github.com/amarbel-llc/moxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amarbel-llc%2Fmoxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34005030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-tools","claude-code","cli","declarative-tools","golang","mcp","model-context-protocol","proxy"],"created_at":"2026-04-16T13:01:50.786Z","updated_at":"2026-06-07T01:01:45.488Z","avatar_url":"https://github.com/amarbel-llc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# moxy\n\nMCP proxy that aggregates multiple child MCP servers into a single unified\nserver.\n\n## Overview\n\nMoxy spawns child MCP servers as subprocesses, communicates with them via\nJSON-RPC over stdio, and presents their tools, resources, and prompts through a\nsingle unified MCP server. Child server capabilities are namespaced with a dot\nseparator (e.g. `grit.status`, `chix.build`).\n\nConfiguration is loaded from a hierarchy of TOML moxyfiles — global\n(`~/.config/moxy/moxyfile`), per-directory, and project-local — with later files\noverriding earlier ones by server name. Moxy also discovers declarative tool\nconfigs called **moxins** from `MOXIN_PATH`, so you can add MCP tools without\nwriting any Go code.\n\n## Why moxy\n\nTraditional MCP servers are standalone programs that each handle their own\nprotocol negotiation, process lifecycle, and output management. Moxy replaces\nthat per-server boilerplate with a shared runtime that provides several features\nout of the box:\n\n**Result caching and progressive disclosure.** Tool outputs exceeding the\ninline-token threshold are streamed into [madder](https://github.com/amarbel-llc/madder)\n(a content-addressable blob store) and replaced with a `madder://blobs/\u003cdigest\u003e`\nURI plus a head/tail summary. Agents see enough to decide whether the full output\nmatters, and can read the full blob with `madder cat \u003cdigest\u003e` (or via the\n`madder://blobs/{digest}` resource) — without blowing up the context window on a\n10,000-line `git log`. Truncation warnings are explicit so agents never mistake\npartial output for complete output. Moxy expects a `.default` store at startup;\nspinclass auto-initializes one per worktree, otherwise run `madder init .default`\nfrom your repo root.\n\n**Composable result URIs.** The `madder://blobs/\u003cdigest\u003e` URIs are first-class\nacross moxin tools. A `folio.read` call can take the URI from a previous\n`rg.search` result as its file path; a `jq.jq` call can take one as stdin.\nMoxy rewrites these to file descriptors at invocation time (piping\n`madder cat \u003cdigest\u003e` stdout through to the child process), so tools chain\nwithout the agent needing to copy data between calls.\n\n**Declarative tool authoring.** Moxins are TOML files — a manifest plus one file\nper tool. Each tool file declares its name, description, input schema, command,\nand args. Moxy handles MCP protocol, argument passing, process invocation,\nresult caching, and permission signaling. No SDK, no boilerplate, no server\ncode.\n\n**Permission control.** Each moxin tool can declare a `perms-request` field:\n`always-allow` (skip confirmation), `each-use` (always prompt), or\n`delegate-to-client` (let the client decide). This lets read-only tools like\n`folio.read` run without interrupting the agent, while destructive tools like\n`grit.push` require explicit approval.\n\n**Unified discovery.** Agents see all tools from all servers through a single MCP\nconnection. Built-in `moxy://` resources let agents introspect available servers,\ntool counts, and full JSON schemas at runtime without additional configuration.\n\n## Install\n\n### Nix\n\n```sh\nnix run github:amarbel-llc/moxy\n```\n\nOr add to your flake inputs for the full package with nix-wrapped moxins.\n\n## Moxins\n\nA moxin is a directory of TOML files that defines an MCP server without any\ncode. The directory contains a `_moxin.toml` manifest and one `.toml` file per\ntool:\n\n```\nmoxins/grit/\n  _moxin.toml        # server name, description\n  log.toml           # tool: show commit history\n  diff.toml          # tool: show changes\n  commit.toml        # tool: create a commit\n  ...\n```\n\nEach tool file declares its input schema, command, and args. Moxy handles\neverything else — MCP protocol, argument passing (schema-ordered, then\nalphabetical), process invocation, result caching, and permission signaling.\nSee [moxin(7)](cmd/moxy/moxin.7) for the full authoring guide.\n\n### Shipped moxins\n\nThe following moxins ship with moxy. Each can be served individually via\n`moxy serve-moxin --name \u003cname\u003e` or aggregated through the proxy.\n\n| Moxin | Tools | Description | Deps |\n|-------|------:|-------------|------|\n| calendar | 1 | Google Calendar: view upcoming events and agendas | bun, gws |\n| car | 5 | Google Drive: search, list, get, and export files | bun, gws |\n| conch | 1 | Shell inspection: syntax checking and script analysis | bash |\n| env | 5 | Environment inspection: PATH binaries and env vars | — |\n| folio | 16 | File I/O. Auto-allows inside CWD, /nix/store, and ~/.claude tree; prompts elsewhere | jq, coreutils |\n| freud | 12 | Past Claude Code session transcripts | python3 |\n| get-hubbed | 31 | GitHub tools (defaults to current repo; pass `repo_owner_name` to target a different repo) | gh, jq, bun |\n| gmail | 2 | Gmail: triage and read messages | bun, gws |\n| grit | 31 | Git operations (force-push/hard-reset blocked on main/master) | git, jq |\n| gws | 1 | Google Workspace: generic API passthrough | bun, gws |\n| hamster | 8 | Go package documentation via `go doc` | go, bun |\n| jq | 1 | Execute jq filters on JSON data | jq |\n| just-us-agents | 6 | Justfile recipe runner | just, jq, bun |\n| man | 4 | Unix man page reader with section-level progressive disclosure | pandoc, mandoc |\n| piers | 13 | Google Docs: read, create, edit, and comment on documents | bun, gws |\n| prison | 1 | Google Sheets: read spreadsheet data | bun, gws |\n| rg | 1 | Ripgrep code search with structured output modes | ripgrep |\n| sisyphus | 10 | Jira Cloud tools | python3, atlassian-python-api |\n| slip | 0 | Google Slides: read and edit presentations | bun, gws |\n\n## Usage\n\n### As a Claude Code plugin\n\n```sh\nmoxy install-claude-plugin\n```\n\nThis registers moxy as a Claude Code MCP server plugin. All moxins discovered\nfrom `MOXIN_PATH` are served through the proxy alongside any servers defined in\nyour moxyfile hierarchy.\n\n### Serve a single moxin\n\n```sh\nmoxy serve-moxin --name grit\n```\n\nServes one moxin as a standalone MCP server over stdio. Useful for registering\nindividual moxins with MCP clients directly.\n\n### Run as MCP proxy\n\n```sh\nmoxy serve-mcp\n```\n\nLoads the moxyfile hierarchy, spawns child servers, discovers moxins, and serves\neverything through a single MCP endpoint on stdio. This is the default command\nwhen invoked via the MCP protocol.\n\n## Configuration\n\nMoxy loads TOML moxyfiles from a directory hierarchy:\n\n1. `~/.config/moxy/moxyfile` (global)\n2. Each parent directory between `$HOME` and the current directory\n3. `./moxyfile` (project-local)\n\nLater files override earlier ones by server name. See\n[moxyfile(5)](cmd/moxy/moxyfile.5) for the full configuration reference.\n\n## Documentation\n\nMoxy ships with man pages:\n\n- **moxy(1)** — command overview and subcommands\n- **moxyfile(5)** — configuration file format and hierarchy\n- **moxy-hooks(5)** — hook configuration for Claude Code integration\n- **moxin(7)** — moxin format and authoring guide\n\nView them with `man moxy`, `man moxyfile`, `man moxy-hooks`, or `man moxin`\nafter installing via Homebrew or nix.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarbel-llc%2Fmoxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famarbel-llc%2Fmoxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famarbel-llc%2Fmoxy/lists"}