Rocky white paper: agentic eng MCP

Version 1.0 | August 2026 Authors: Radjiv, hellozheat Repository: github.com/hellozheat/rocky Docs source: docs/ Reference: Public technical deep dive

Abstract

Rocky is an MCP server for agentic-assisted engineering. Your model still writes code in your repo. Rocky supplies a shared handbook (agents + rules + skills), one devkit gateway tool, graphify-first discovery, and a pre-PR quality gate with a clear ready / not_ready verdict.

It is assisted, not autonomous. The product value is less thrashing: shared conventions, structured tool JSON instead of pasted terminals, scoped tests, and a gate before humans review.

On a measured production React monorepo feature (same model, same task), midpoint session tokens moved from about 255k to about 89k (about 65% less). Discovery alone dropped about 89%. OpenRouter Sonnet 4.6 cost on that example moved from about $1.62 to about $0.85.

MCP endpoint: https://userocky.zheat.xyz/mcp Inspector: userocky.zheat.xyz/inspector License: MIT

Table of Contents

1. Problem Statement
2. Design Principles
3. Architecture Overview
4. The devkit Gateway
5. Handbook: Agents, Skills, Rules
6. Architecture Profiles
7. Senior Workflow
8. Measured Value Report
9. Token and Cost Economics
10. Install and Security
11. Clients and Prompts
12. Solo Dev vs Team
13. Limitations and Future Work
14. Related Insights
15. Appendices

1. Problem Statement

AI coding tools are fast. Much of what they generate still gets rejected: wrong conventions, inconsistent patterns, missing tests, structure a reviewer will not accept.

Without shared tooling, each session rediscovers the repo, re-guesses standards, and re-runs huge test and lint cycles. That burns two things: review time on bad output, and tokens regenerating it.

Typical without-Rocky path:

10-20+ file reads to "understand" the repo
Full test suite on every fix loop
Long yarn lint / yarn test logs pasted into chat
No structured ready / not_ready before PR
Solo prompts reinvented per project

Rocky exists for that gap: team-grade handbook + small safe repo actions, even when you are solo and connecting a public server.

2. Design Principles

3. Architecture Overview

Rocky is an HTTP MCP server. Clients (Cursor, Claude Code, VS Code, ChatGPT) connect to /mcp. The server exposes resources, prompts, and tools.

┌────────────────────────────────────────────────────────────┐
│  Host (Cursor / Claude Code / VS Code / ChatGPT)           │
│  Model still writes code in the user clone                 │
├────────────────────────────────────────────────────────────┤
│  MCP: https://userocky.zheat.xyz/mcp                       │
│  - Resources: devkit://how-it-works, handbook/..., caps    │
│  - Prompts: start-task, review-code, before-pr, learn      │
│  - Tools: devkit gateway (+ standalone debug twins)        │
├────────────────────────────────────────────────────────────┤
│  Handbook (server-side)                                    │
│  - 24 agents  (~1,244 lines total on disk)                 │
│  - 26 skills  (templates / checklists, on demand)          │
│  - Rules (.mdc) for team conventions                       │
├────────────────────────────────────────────────────────────┤
│  Repo actions (when path allowlisted)                      │
│  - repo_lint, repo_test, test_gap_finder                   │
│  - change_scope_analyzer, pre_pr_quality_gate              │
│  - optional repo_open_pr (needs GITHUB_TOKEN)              │
└────────────────────────────────────────────────────────────┘

Source docs: INSTALL.md, using-mcp-devkit-report.md, why-agents-and-skills-are-split.md.

4. The devkit Gateway

Listing dozens of MCP tools burns context on schemas. Rocky exposes a single `devkit` tool with an action field. The model learns operations from devkit://capabilities once, then reuses one schema.

Tradeoff: each call still sends the full devkit schema. On long sessions that is usually cheaper than 15+ separate tool definitions.

Standalone tools (project-intelligence, pre-pr-quality-gate, …) duplicate gateway actions. Prefer devkit in chat. Use standalone tools for Inspector / debug.

Use structured: true on intelligence tools when the host parses JSON. That avoids re-parsing markdown.

5. Handbook: Agents, Skills, Rules

5.1 One sentence

Agents are the short front door; skills are the deep reference you load only when the task needs templates or long checklists.

Source: why-agents-and-skills-are-split.md.

5.2 Why split

Disciplined session: about 4k-6k tokens of handbook overhead, not the whole corpus.

5.3 Agent skeleton

Every agent shares:

5.4 Snapshot counts (README)

Agents (24): architecture/app (react-hexagonal, nextjs-developer, node-api-developer, nestjs-hexagonal, fastapi-hexagonal, typescript-library-developer), testing/quality (vitest-writer, playwright-writer, storybook-writer, Nest/Python writers, tester-qa, pr-quality-gate, code-reviewer), discovery/workflow (codebase-discovery, graphify agents, coverage-and-review-workflow), support (product-owner, documentation-writer, code-simplifier, tailwind-ui-developer, k3s-devops).

Skills (26): stack build playbooks, testing/review, ops/security/perf, product/design.

Rules: team .mdc under src/mcp/rules/ (e.g. human-readable-code, codebase-conventions, react-components, tests).

5.5 Routing

devkit-start-task uses a router table (task area → agent + rules) and a cap: read at most 2-3 handbook resources. It does not embed all rule/agent URIs.

devkit-review-code points to exactly three: code-reviewer, human-readable-code, tests.

6. Architecture Profiles

Detect the user's repo before imposing structure. Prefer hexagonal when src/domain/ exists.

Source: architecture-profiles.md.

Detection order

1. app/ + Next.js deps → nextjs-app-router (nextjs-developer)
2. src/domain/ + src/application/ → hexagonal

- NestJS → nestjs-hexagonal - FastAPI / Python → fastapi-hexagonal - React UI → react-hexagonal

1. src/components/atoms + connected/ → layered-react-spa (legacy)
2. No components/ but src/routes or Express → node-api-only
3. Else: graphify + read neighbors. Do not force foreign layouts.

Hexagonal (preferred when present)

src/
├── domain/           # entities, ports, pure logic
├── application/      # use-cases / hooks / controllers / routes
└── infrastructure/   # adapters (api, db, email, …)

Styling variants

7. Senior Workflow

End-to-end pipeline the handbook and MCP tools reinforce.

Source: senior-workflow.md.

flowchart LR
  A[Connect Rocky MCP]
  B[devkit-start-task]
  C[codebase-discovery]
  D[1 agent + 1-2 rules]
  E[Edit user repo]
  F[repo_test / repo_lint]
  G[pre_pr_quality_gate]
  A --> B --> C --> D --> E --> F --> G

1. Discover : graphify workflow, list_handbook if needed, project_intelligence
2. Match conventions : codebase-conventions, react-components, human-readable-code; pick stack agent
3. Implement : small reviewable diffs; read neighbors; no drive-by refactors
4. Verify locally : yarn lint:fix, yarn test, yarn build in the target project
5. Pre-PR gate : fix blockers; address warnings; re-run until verdict: "ready"
6. Open PR : repo_open_pr when asked and token configured; drafts OK for large changes

Example prompt:

Use Rocky: read devkit://how-it-works, list_handbook, and the matching stack agent.
Implement changes directly in this repo, then run pre_pr_quality_gate before we finish.
Do not only call MCP tools without editing files.

8. Measured Value Report

Source: using-mcp-devkit-report.md. Same kind of agentic-assisted task: implement or fix something, add tests, get review-ready.

8.1 Side-by-side

8.2 Measured example (one production feature)

8.3 Tokens by phase (midpoint, thousands)

Discovery 125 vs 14 is the story: briefing vs walking every room.

8.4 Sonnet 4.6 cost by phase (example)

OpenRouter list rates used in the report (May 2026): $3/M input, $15/M output on Claude Sonnet 4.6.

For dollar proof on your stack, compare two similar tickets on your Cursor/OpenRouter dashboard. Plans change; the relative shape matters more than a frozen price.

9. Token and Cost Economics

Source: token-cost-breakdown.md.

9.1 What saves tokens

• Router : read 2-3 handbook files, not 24 agents
• Gateway JSON : test_gap_finder, change_scope_analyzer, repo_lint vs pasted terminals
• Scoped tests : less log volume
• Graphify summary-first : not full GRAPH_REPORT.md in the thread
• One gate before PR : cheaper than two style/lint review rounds

9.2 What wastes tokens

• list_handbook then reading every agent body (about 10k-25k+ tokens)
• Ignoring the router and loading all skills
• Pasting graphify-out/ wholesale into chat
• Full suite every message when scoped runs exist

9.3 Session bucket table (directional)

9.4 Relative step cost

10. Install and Security

Source: INSTALL.md.

Quick connect (hosted)

Claude Code

claude mcp add --transport http "rocky" https://userocky.zheat.xyz/mcp

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "rocky": {
      "url": "https://userocky.zheat.xyz/mcp"
    }
  }
}

VS Code / ChatGPT: open userocky.zheat.xyz/mcp or paste the URL in MCP connector settings.

Deploy your own

git clone https://github.com/hellozheat/rocky.git
cd rocky
yarn install
yarn build
yarn deploy

Requirements: Node.js 20+, Yarn. Optional on user machines: graphify CLI; Understand Anything plugin.

Environment

Security checklist (production)

• No MCP login on /mcp by default. Put your own reverse proxy or network controls in front if the URL is public.
• Never commit .env or tokens.
• Prefer handbook-only public hosting: no GITHUB_TOKEN, no broad DEVKIT_ALLOWED_REPO_ROOTS, unless you add auth in front.
• If repo tools are enabled, set DEVKIT_ALLOWED_REPO_ROOTS to the smallest set of git roots required.
• `safe-run`: allowlisted commands only (git, yarn, eslint, graphify, …), not a general shell.

11. Clients and Prompts

Built-in prompts:

12. Solo Dev vs Team

Repo-scoped actions need DEVKIT_ALLOWED_REPO_ROOTS (or local stdio) pointing at your clone. That is path config, not team membership.

13. Limitations and Future Work

Current limits

1. Model must follow the router. Over-reading the handbook erases the token win.
2. Repo tools need path access. Handbook-only hosting cannot run repo_test on your laptop clone without allowlisting (or local server).
3. Not a CI replacement. Merge gates stay in your pipeline.
4. Measured numbers are one production feature. Directional for other stacks; re-measure on your tickets.
5. No MCP auth by default. Operators must add proxy/network controls for exposed URLs.

Future directions

1. Tighter graphify ↔ discovery integration in the gateway
2. Broader stack agents as the handbook grows
3. Clearer host-native attach of skills without dumping them into every turn
4. Optional stronger auth modes for multi-tenant hosted Rocky

14. Related Insights

Shorter pieces derived from the same docs:

• I shipped a free MCP server for devs. It's called Rocky.
• Using Rocky: agentic-assisted programming value report
• Token and cost breakdown
• Why Rocky splits agents and skills
• Rocky architecture profiles
• Rocky senior workflow
• Sibling skills: Humaniseur white paper, No More Slop white paper

15. Appendices

Appendix A: Docs map

Appendix B: Manager one-liner

Same model, about 40-50% fewer tokens on a typical feature when Rocky is connected and the model follows the router (estimate). On the measured example, about 65% fewer tokens and about $1.62 → $0.85 Sonnet cost.

Appendix C: Engineer checklist

1. Connect Rocky; confirm MCP is green.
2. Start with devkit-start-task or the README example prompt.
3. Read codebase-discovery once per repo; pick one router row.
4. Use repo_test / scoped tests, not full suite every message.
5. Run pre_pr_quality_gate before repo_open_pr.

Rocky as documented in [github.com/hellozheat/rocky](https://github.com/hellozheat/rocky) `docs/`. Counts, prompts, and measured figures live with the source and may evolve without a new white-paper revision.