{
"markdown": "\n\n# @rotifer/mcp-server\n\n[](https://www.npmjs.com/package/@rotifer/mcp-server)\n[](LICENSE)\n[](https://nodejs.org/)\n[](https://modelcontextprotocol.io)\n\n**Build, compose, and run AI agents — directly from your IDE.**\n\nSearch genes, create agents with composable genomes, run pipelines in a WASM sandbox, and compete in the Arena.\nZero config. Works with Cursor, Claude Desktop, Windsurf, and any MCP-compatible client.\n\n
\n\n---\n\n## Quick Start\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"rotifer\": {\n \"command\": \"npx\",\n \"args\": [\"@rotifer/mcp-server\"]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"rotifer\": {\n \"command\": \"npx\",\n \"args\": [\"@rotifer/mcp-server\"]\n }\n }\n}\n```\n\n### Windsurf / Other MCP Clients\n\nUse the same `npx` command — any client that supports MCP stdio transport will work.\n\n## What Can It Do?\n\n### Create and run an agent in one conversation\n\n```\nYou: \"Build me an agent for code security scanning\"\nAI: → create_agent({ agent_name: \"sec-bot\", gene_ids: [\"security-scanner\", \"genesis-code-format\"],\n composition: \"Seq\" })\n Agent 'sec-bot' created with 2-gene Seq genome.\n\nYou: \"Run it on my project\"\nAI: → agent_run({ agent_name: \"sec-bot\", input: \"{\\\"path\\\":\\\"./src\\\"}\" })\n Pipeline complete — 3 findings, 0 critical.\n```\n\n### Search, compare, and compose genes\n\n```\nYou: \"Find the best gene for web search\"\nAI: → search_genes({ query: \"web search\" })\n Found 8 genes. Top match: genesis-web-search (F(g) = 0.87, Native)\n\nYou: \"Compare it against the lite version\"\nAI: → compare_genes({ gene_ids: [\"...\", \"...\"] })\n Side-by-side: success rate, latency, fitness breakdown\n```\n\n### Full gene lifecycle from your IDE\n\n```\nYou: \"Wrap my function as a gene\"\nAI: → wrap_gene({ gene_name: \"my-search\", domain: \"search.web\", fidelity: \"Wrapped\" })\n → compile_gene({ gene_name: \"my-search\" })\n → test_gene({ gene_name: \"my-search\", compliance: true })\n → publish_gene({ gene_name: \"my-search\", changelog: \"Initial release\" })\n```\n\n## Tools (31)\n\n### Discovery & Analytics\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `search_genes` | Search the Gene ecosystem by name, domain, or description | `query`, `domain`, `fidelity`, `sort` (`relevance`/`newest`/`popular`/`fitness`), `page`, `per_page` |\n| `get_gene_detail` | Get detailed info about a Gene (phenotype, fitness, metadata) | `gene_id`, `content_hash` (either identifies the gene) |\n| `get_arena_rankings` | Arena rankings for a domain, sorted by F(g) fitness | `domain`, `page`, `per_page` |\n| `compare_genes` | Side-by-side fitness comparison of 2–5 Genes | `gene_ids` (array) |\n| `get_gene_stats` | Download statistics (total, 7d, 30d, 90d) | `gene_id` |\n| `get_leaderboard` | Creator reputation leaderboard | `limit` |\n| `get_developer_profile` | Creator public profile and reputation | `username` |\n| `get_gene_reputation` | Detailed reputation breakdown (Arena, Usage, Stability) | `gene_id` |\n| `list_gene_versions` | Version history chain with changelogs | `owner`, `gene_name` |\n| `suggest_domain` | Suggest matching domains from the registry | `description` |\n\n### Local Workspace\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_local_genes` | Scan local workspace for installed Genes | `project_root`, `domain`, `fidelity` |\n| `list_local_agents` | List Agents in the local workspace | `project_root`, `state` |\n\n### Gene Lifecycle\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `init_gene` | Initialize a new Gene project with starter files | `gene_name`, `fidelity`, `domain`, `no_genesis` |\n| `scan_genes` | Scan for candidate functions or SKILL.md files | `path`, `skills`, `skills_path` |\n| `wrap_gene` | Wrap a function/skill as a Gene | `gene_name`, `domain`, `fidelity`, `from_skill`, `from_clawhub` |\n| `test_gene` | Test a Gene (schema validation + sandbox) | `gene_name`, `verbose`, `compliance` |\n| `compile_gene` | Compile a Gene to WASM IR | `gene_name`, `check`, `wasm_path`, `lang` |\n| `doctor` | Check the local TypeScript→WASM toolchain (esbuild / javy) and report what is missing — read-only; use when `compile_gene` fails | `project_root` |\n| `run_gene` | Execute a local Gene | `gene_name`, `input`, `verbose`, `no_sandbox`, `trust_unsigned` |\n| `publish_gene` | Publish to Rotifer Cloud | `gene_name`, `all`, `description`, `changelog`, `skip_arena`, `skip_security` |\n| `install_gene` | Install a Gene from Cloud Registry. `force` snapshots the copy it replaces | `gene_id`, `project_root`, `force` |\n| `rollback_gene` | Undo the last overwrite of a local Gene; call with no name to list what can be undone | `gene_name`, `project_root` |\n| `vg_scan` | V(g) security scan — static analysis for Gene/Skill code safety | `path`, `gene_id`, `all`, `project_root` |\n| `arena_submit` | Measure a local Gene in the sandbox and submit the measurement to the Arena. Scores are produced by running the Gene, never supplied by the caller | `gene_name`, `project_root` |\n\n### Agent Composition\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `create_agent` | Create an Agent composing multiple Genes | `agent_name`, `gene_ids`, `composition` (`Seq`/`Par`/`Cond`/`Try`/`TryPool`), `domain`, `top`, `strategy`, `par_merge` |\n| `agent_run` | Run a local Agent by name | `agent_name`, `input`, `verbose`, `no_sandbox` |\n\n### Authentication & Analytics\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `auth_status` | Check login status | — |\n| `login` | OAuth login (GitHub/GitLab) | `provider`, `endpoint` |\n| `logout` | Clear credentials | — |\n| `get_mcp_stats` | MCP call analytics | `days` |\n| `get_my_reputation` | Current user's reputation | — |\n\n## Resources (7)\n\nMCP Resources let AI clients reference Rotifer data as context:\n\n| URI Template | Description |\n|---|---|\n| `rotifer://genes/{gene_id}/stats` | Gene download statistics |\n| `rotifer://genes/{gene_id}` | Gene detail + phenotype |\n| `rotifer://developers/{username}` | Creator profile + reputation |\n| `rotifer://leaderboard` | Top creators by reputation score |\n| `rotifer://local/genes` | Local Gene inventory |\n| `rotifer://local/agents` | Local Agent registry |\n| `rotifer://version` | MCP Server version and update availability |\n\nEach resource returns what the tool of the same job returns, so a declared tool\nset covers both: with `--tools=evolve`, `rotifer://genes/{gene_id}/stats`,\n`rotifer://developers/{username}` and `rotifer://leaderboard` disappear from the\nlisting and are refused if read directly, because `get_gene_stats`,\n`get_developer_profile` and `get_leaderboard` were not asked for.\n`rotifer://version` always answers — it is the server describing itself, not a\ncapability. Before 0.16.0 these were reachable whatever the tool set said.\n\n## Prompts (4)\n\nMCP Prompts give AI clients guided workflows for common tasks:\n\n| Prompt | Description | Key Arguments |\n|--------|-------------|---------------|\n| `rotifer-hello` | Interactive agent creation — pick a template and run immediately | `template`, `input` |\n| `rotifer-guide` | Understand Rotifer Protocol — genes, agents, Arena, fidelity model | — |\n| `rotifer-architect` | Design an Agent — task-driven gene search + composition planning | `task` |\n| `rotifer-challenge` | Arena evaluation — submit a gene, compare with competitors | `gene` |\n\nTry asking your AI: *\"Use the rotifer-hello prompt to build me an agent\"* or *\"Use rotifer-architect to design an agent for document Q&A\"*.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│ AI IDE (Cursor / Claude / Windsurf) │\n│ │\n│ \"Find genes for code formatting\" │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ MCP Client │ │\n│ │ (stdio transport) │ │\n│ └────────┬────────────┘ │\n└───────────┼─────────────────────────────────────┘\n │ MCP Protocol\n ▼\n┌─────────────────────────────────────────────────┐\n│ @rotifer/mcp-server │\n│ │\n│ 30 Tools 7 Resources 4 Prompts Local Scanner│\n│ ┌──────────┐ ┌───────────┐ ┌────────────┐ │\n│ │ discover │ │rotifer:// │ │ ./genes/ │ │\n│ │ lifecycle│ │genes/stats│ │ phenotype │ │\n│ │ agents │ │developers │ │ agents │ │\n│ │ auth │ │leaderboard│ └────────────┘ │\n│ └────┬─────┘ └─────┬─────┘ │ │\n└───────┼──────────────┼────────────────┼─────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────┐\n│ Rotifer Cloud API Local File System │\n│ (Supabase) (genes/, .rotifer/) │\n└─────────────────────────────────────────────────┘\n```\n\n## Configuration\n\nZero-config by default — connects to the public Rotifer Cloud API.\n\nTo use a custom endpoint, create `~/.rotifer/cloud.json`:\n\n```json\n{\n \"endpoint\": \"https://your-supabase-instance.supabase.co\",\n \"anonKey\": \"your-anon-key\"\n}\n```\n\nOr set environment variables:\n\n```bash\nROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co\nROTIFER_CLOUD_ANON_KEY=your-anon-key\n```\n\n### Choosing which tools to expose\n\nAll thirty-one tools are available by default. `ROTIFER_MCP_TOOLS` narrows that\nto what a given integration actually needs — useful when the server is attached\nto an assistant that should not be able to publish or log in on your behalf:\n\n```bash\nnpx @rotifer/mcp-server --tools=evolve # the rank-and-swap preset (10 tools)\nnpx @rotifer/mcp-server --tools=readonly # nothing that writes (14 tools)\nROTIFER_MCP_TOOLS=search_genes,get_gene_detail # an exact list\nROTIFER_MCP_TOOLS=evolve,vg_scan # a preset plus one\n```\n\nThe flag and the variable do the same thing, and the flag wins if both are set.\nBoth exist because callers differ in what they can reach: a shell user sets the\nvariable, while something launching this server from a manifest controls only\nthe command line.\n\nA declared set covers the whole surface, not just `tools/list`. Tools outside it\nare refused when called by name; [resources](#resources-7) that duplicate an\nexcluded tool are dropped from the listing and refused when read; and the\nsandbox escape hatches below stay off unless separately declared. A restriction\nwith an unlisted way around it is not a restriction.\n\nTools outside the set disappear from `listTools` and are refused if called\nanyway. The refusal says how to add the tool back and, where one exists, the\n`rotifer` CLI command that does the same job — so a narrowed set is a boundary\nyou can see and cross deliberately, not a dead end.\n\nLeave it unset and nothing changes.\n\n### Switching off the sandbox\n\n`agent_run` and `run_gene` take `no_sandbox`, and `run_gene` also takes\n`trust_unsigned` — options that run Gene code as plain Node.js instead of inside\nthe WASM sandbox. Narrowing the tool set would mean little if a tool inside the\nnarrowed set could still do that, so these are refused unless declared at\nlaunch:\n\n```bash\nnpx @rotifer/mcp-server --allow=no-sandbox\nnpx @rotifer/mcp-server --allow=no-sandbox,trust-unsigned\nROTIFER_MCP_ALLOW=no-sandbox # same thing\n```\n\nNothing is removed. The option moves from \"any caller can set it\" to \"someone\ndeclared it at launch\", and you can always do it yourself:\n\n```bash\nrotifer agent run --no-sandbox\nrotifer run --trust-unsigned\n```\n\nWhat changes is that an assistant can no longer decide to unsandbox on its own.\nPassing `no_sandbox: false` is asking for the safe behaviour and is never\nrefused.\n\n### Undoing an install\n\n`install_gene` with `force` used to overwrite a Gene with no way back. It now\nmoves the old copy into `/.snapshots/` first, and `rollback_gene` puts it\nback:\n\n```\nrollback_gene {} → what can be rolled back\nrollback_gene { gene_name: \"formatter\" } → restore the copy that was replaced\n```\n\nOne snapshot per Gene: the next overwrite of that Gene supersedes it, and a\nrollback consumes it. This undoes the last upgrade rather than keeping a\nhistory — `list_gene_versions` already answers what versions exist upstream.\n\n### Usage reporting\n\nWhen you are **signed in**, each tool call reports a usage record to Rotifer\nCloud: the tool's name, the Gene id it acted on, whether it succeeded, how long\nit took, and your user id. That is what `get_mcp_stats` reads back. Running a\nGene also records the invocation, which the protocol's anti-manipulation\nmetrics depend on.\n\nIt does **not** send the arguments you pass, the contents of any file, your\nenvironment variables, or your local configuration.\n\n**Signed out, no usage record is sent.** One request does go out either way:\ninstalling a Gene bumps that Gene's public install counter. It carries the Gene\nid and nothing else — no user id, no session, no arguments — and it is how the\nArena counts installs. Until 0.15.1 nothing stopped it, and this section said\n\"signed out, nothing is reported\", which was not true of an install.\n\n`ROTIFER_TELEMETRY=0` now stops all three:\n\n```bash\nROTIFER_TELEMETRY=0 # also accepts false / off\n```\n\nThe three are `logMcpCall`, `logGeneInvocation` and the `track_download` call\ninside `installGene`, all in [`src/cloud.ts`](src/cloud.ts) — short enough to\nread in full. Nothing else here reports anything on its own: every other\noutbound call in this server is a tool you invoked doing its job — a query, a\npublish, a sign-in — plus the WASM artifact download and one npm version check\nper day.\n\n## Requirements\n\n- Node.js >= 20\n\n## Pair with the CLI\n\nThis MCP server works best alongside the [Rotifer CLI](https://github.com/rotifer-protocol/rotifer-playground). The CLI provides the local runtime (WASM sandbox, Arena engine, IR compiler) while the MCP server exposes it all to your AI assistant:\n\n```bash\nnpm install -g @rotifer/playground\nrotifer init my-agent && cd my-agent\nrotifer hello --template quality-advisor # your first Agent workspace in seconds\n```\n\n## Links\n\n- [Rotifer Protocol](https://rotifer.dev) — Main site\n- [MCP Setup Guide](https://rotifer.dev/docs/guides/mcp-setup) — Step-by-step setup\n- [Gene Marketplace](https://rotifer.ai) — Browse and discover Genes\n- [CLI Playground](https://github.com/rotifer-protocol/rotifer-playground) — Build and test Genes locally\n- [Protocol Specification](https://github.com/rotifer-protocol/rotifer-spec) — Formal spec\n\n## License\n\nApache-2.0\n",
"bytes": 15139,
"sha": "4713e5d65ae8160e3df06d9d7b9ecd0ec24148b0cf5d2f3d9c9a523bdfe15ea1",
"repo_slug": "rotifer-protocol/rotifer-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_rotifer_protocol_mcp_server_e1af69ab/readme"
}