Use this? Here's everything you need. One URL, no auth, 30 seconds.

URL:  https://emin-mcp.emino.workers.dev/mcp
Auth: none

---

Connect your agent

Pick your tool, copy the config. Done.

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  emin:
    type: http
    url: https://emin-mcp.emino.workers.dev/mcp
    transport: streamable-http

opencode

// opencode.json
{
  "mcp": {
    "emin": {
      "type": "http",
      "url": "https://emin-mcp.emino.workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Claude Code

// .claude/mcp.json or VS Code settings
{
  "mcpServers": {
    "emin": {
      "type": "http",
      "url": "https://emin-mcp.emino.workers.dev/mcp"
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "emin": {
      "transport": "sse",
      "url": "https://emin-mcp.emino.workers.dev/mcp"
    }
  }
}

Continue

// config.json
{
  "experimental": {
    "mcpServers": {
      "emin": {
        "transport": "sse",
        "url": "https://emin-mcp.emino.workers.dev/mcp"
      }
    }
  }
}

Generic SSE client

Endpoint: POST https://emin-mcp.emino.workers.dev/mcp
Headers:  Accept: application/json, text/event-stream

Run it locally instead

git clone https://github.com/eminogrande/emin-mcp.git
cd emin-mcp && npm install

Then point your tool at node /path/to/emin-mcp/src/index.mjs (stdio).

---

What your agent gets

Three resources, read automatically on session start. Four tools for mechanical enforcement.

Resource	Content
rules://emin/global	16 working rules: TLDR first, never invent features, ask before irreversible actions, document every decision, …
rules://emin/tooling	Mandatory tools: ponytail (YAGNI), nuanced (call-graph), repowise (file health), task-master (PRD→tasks)
rules://emin/coding	15 evidence-derived coding rules: zeroize buffers, no silent fallbacks, scope-drift = stop, hostile self-review, …

Tool	What it does
scope_check	Checks if a diff stayed within planned scope (files + LOC). Enforces rule #3.
secrets_check	Scans text for API keys, tokens, private keys, mnemonics. Enforces rule #14.
rule_check	Scans diff for unsafe casts, silent fallbacks, missing zeroize. Enforces rules #5, #6, #9, #10.
handoff	Validates structured subagent handoff context. Enforces tooling rule #6.

Verify it's working:

curl -s -X POST https://emin-mcp.emino.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list"}'

---

FAQ (using, not developing)

Q: Do I need an API key? No. The rules are public. No auth, no token, no signup.

Q: Can I use this for my own rules? Yes — fork the repo, replace src/rules/*.mjs, deploy your own Worker. The structure is generic; the rules are personal.

Q: What if the Worker is down? Run it locally: git clone, npm install, point your tool at src/index.mjs. Same rules, no network dependency.

Q: Which tools does this work with? Any MCP-compatible client. Tested: Hermes Agent, opencode, Claude Code, Cursor, Continue. If your tool speaks MCP over HTTP/SSE or stdio, it works.

---

---

Everything below is for developers working ON emin-mcp, not just using it.

---

Project structure

src/
├── index.mjs          # Stdio entry point (local) — 8 lines
├── worker.mjs         # HTTP entry point (Cloudflare Worker) — 12 lines
├── server.mjs         # createServer() — shared resource + tool registration
├── version.mjs        # Single VERSION constant
├── rules/
│   ├── global.mjs     # Working rules
│   ├── tooling.mjs    # Tool install + usage instructions
│   └── coding.mjs     # Evidence-derived coding rules (capped at 15)
├── checks/            # Pure functions — zero deps (no MCP, no Zod)
│   ├── scope.mjs      # checkScope()
│   ├── secrets.mjs    # checkSecrets()
│   ├── rules.mjs      # checkRules()
│   └── handoff.mjs    # checkHandoff()
├── tools/             # MCP wrappers — Zod schemas, call checks/
│   ├── scope_check.mjs
│   ├── secrets_check.mjs
│   ├── rule_check.mjs
│   └── handoff.mjs
└── sdk/
    └── index.mjs      # Client library — imports from checks/, zero deps
scripts/
└── selfcheck.mjs      # 95 assertions — boots server, reads resources, calls tools
.github/workflows/
├── ci.yml             # Selfcheck on PRs
└── deploy.yml         # Auto-deploy to Cloudflare on push to master
wrangler.toml           # Cloudflare Worker config
package.json            # Two dependencies: @modelcontextprotocol/sdk + zod

Two entry points, one source of truth. Both import from the same src/rules/ files. Selfcheck enforces they stay in sync.

Selfcheck

npm run selfcheck   # 34 assertions, all must pass

Deploy

npx wrangler deploy

How to add a new rule

1. Find a real bug in an agent's commit
2. Identify the failure class
3. Write a mechanical check that would have caught it
4. Add the commit SHA as evidence
5. If at 15 coding rules, merge or drop the weakest
6. Update scripts/selfcheck.mjs
7. npm run selfcheck — all must pass
8. npx wrangler deploy
9. Add entry to Development Journal below

---

Development Journal

Every commit, every decision, every thought process. Read chronologically.

⚠️ This is a chronological log — not a reference manual. Each entry describes the state of the product at that point in time. Later entries may override, undo, or break earlier ones. The current state is what the live server serves at https://emin-mcp.emino.workers.dev/mcp. If an old entry says "two resources" but the live server returns three, the live server wins. This is the only documentation file — there is no separate FAQ, CHANGELOG, or LOGBUCH. Everything lives here.

2026-07-05 · 939505d — Initial commit

What: First working version. Two MCP resources (rules://emin/global, rules://emin/tooling), stdio transport, selfcheck script.

Why: Emin was tired of maintaining the same rules in different formats for different AI coding tools — CLAUDE.md for Claude Code, AGENTS.md for opencode, .cursorrules for Cursor. Every tool needed its own copy, and they drifted out of sync. An MCP server solves this: one source of truth, every MCP-compatible client reads from the same place.

Decision: MCP server, not a file. CLAUDE.md ties you to one tool. MCP is the standard — every major AI coding tool speaks it. Also: MCP gives room to add enforcement tools later (like scope_check to verify a diff didn't drift from the plan) without changing the transport.

Decision: Resources, not tools. YAGNI. The server instructs agents to use ponytail and nuanced — it does not wrap them. Tools will be added when a real enforcement need shows up, not before.

Decision: Selfcheck, not a test framework. A single script that boots the server over stdio, sends JSON-RPC messages, and asserts the responses. No Jest, no Vitest — just assertions. Keeps the dependency footprint at exactly one package (the MCP SDK).

2026-07-05 · 605a65b — Sharpen rules

What: Two new global rules, two sharpened existing rules, subagent delegation rule in tooling, Firecrawl instruction in tooling.

Why: Emin caught the agent on specific loopholes in the existing rules: re-arguing decisions he'd already made, skipping comprehension before editing, and asking permission after doing something irreversible instead of before. The rules needed to close those gaps explicitly.

Decision: Subagent delegation rule. Tasks that burn context (long docs, browsing, exploring codebases) should be delegated to a subagent. The subagent returns compressed signal — file paths, line numbers, relevant snippets, decisions — not a brain dump. Default threshold: if a step reads more than ~3 files or fetches external content, delegate it.

Mistake: Firecrawl was premature. The commit also added a Firecrawl instruction. Emin flagged it immediately — it was only an idea, not a decision. The agent broke its own rule #1 (don't invent unrequested scope). Reverted in the next commit.

2026-07-05 · 09f49a8 — Revert Firecrawl

What: Removed the Firecrawl instruction from tooling rules.

Why: Emin hadn't decided to use Firecrawl. The agent added it because it seemed useful, but that's exactly what rule #1 forbids: "Not mentioned = not built. Suggestions, not implementations."

Lesson: Even when an addition seems obviously useful, if Emin didn't ask for it, it doesn't go in. The subagent delegation rule stayed because Emin did approve that one.

2026-07-05 · e5eb546 — .context/ folder convention

What: New tooling rule: persist distilled external knowledge in .context/<topic>.md per project.

Why: Emin wanted digested SDK docs, API references, and repo explorations to survive across sessions. Without this, every new session re-digests the same external sources, burning tokens and time.

Decision: Delegate the digest, store the result. The agent delegates the heavy reading to a subagent, which returns a compressed summary. That summary goes into .context/<topic>.md with a standard structure: title, date, sources, key findings, open questions, "approved by Emin?" status. If the source was 5000 lines, the context file is 50.

2026-07-05 · c95bcd9 — Tooling: install + usage for ponytail and nuanced

What: Expanded the tooling resource from "use ponytail and nuanced" to full install instructions per client and exact command/tool references.

Why: The original tooling resource named the tools but left install steps implicit. Every new client had to re-derive how to install and configure them. Emin decided the resource should be self-contained: install snippets for opencode, Claude Code, Codex, Gemini; the ponytail ladder; the full nuanced tool list; license activation; and the compose rule.

Decision: Self-contained instructions. The MCP server is the single source of truth — agents shouldn't need to search the web to figure out how to use the tools it mandates. Selfcheck extended to assert the new content is present.

2026-07-05 · 76df11a — Tooling: add repowise

What: Repowise added as the third mandatory tool in the tooling resource.

Why: Emin decided repowise closes a gap neither ponytail nor nuanced covers: WHICH FILE BREAKS NEXT. Ponytail tells you WHAT to build (YAGNI). Nuanced tells you HOW to edit (call-graph-aware). Repowise tells you WHERE to edit — it gives a defect-validated 1-10 health score per file (ROC AUC 0.74), hotspots, dead code, architectural decisions, and agent provenance.

Decision: Repowise stays its own MCP server. Like nuanced, emin-mcp only instructs agents to install and use it. It does not wrap it. Selfcheck extended with 7 new assertions for repowise content.

2026-07-05 · 632ec23 — Cloudflare Worker + answer-format rule + task-master

What: Three changes in one commit:

1. Cloudflare Worker entry point (src/worker.mjs) for MCP-over-HTTP
2. Global rule 15: answers must be compact tables or bullets, never text walls
3. Task-master added as the fourth mandatory tool

Why (Worker): Emin wanted the rules publicly accessible without requiring a local process. A Cloudflare Worker serves the same rules over HTTP for browser-based tools, remote agents, or any client that can't spawn a local Node process. No auth — the rules are public knowledge, not secrets.

Why (answer-format rule): Emin was getting text-wall answers from agents. The rule enforces: compact tables or bullets, one glance to understand, what / how to test / commit message in short scannable columns.

Why (task-master): Any feature bigger than 3 tasks needs structured planning. Task-master takes a PRD and generates tasks.json with dependencies, status, and priority. Stops the "huge plan, no overview" problem.

Decision: Two entry points, same rules. src/index.mjs for local stdio, src/worker.mjs for Cloudflare HTTP. Both import from the same rule source files. One truth, two transports.

Mistake (discovered later): The Worker only registered global and tooling resources. When coding rules were added in the next commit, the Worker was never updated. This divergence wasn't caught until 2026-07-08.

2026-07-05 · 31c49f3 — Coding rules

What: Third resource: rules://emin/coding. 15 evidence-derived rules for code-writing agents, each with a failure class, mechanical check, and commit SHA as evidence.

Why: The coding agent (GLM) kept repeating the same failure classes in benchmark runs: truncated files causing syntax errors, missing buffer zeroize, compliance-theater helpers that were never called, unsafe casts. Emin wanted a strict, checkable ruleset that would stop these mechanically.

Decision: Evidence-derived, not theoretical. Every rule comes from a real bug found in an agent's commit. The format is: failure class → mechanical check → one-line incident as evidence. No rule exists without a commit SHA proving it was needed.

Decision: Hard cap at 15 rules. The cap forces curation. When a new failure class is discovered, the weakest existing rule is merged or dropped. Repeat offenses strengthen a rule's evidence line instead of adding rules. This prevents rule-bloat where agents ignore a wall of text.

Decision: Generalized failure classes, not incidents. The rules describe patterns ("check-then-create on shared state needs a mutex"), not specific bugs ("the keychain getOrCreateKey race in commit X"). This makes them applicable across projects.

Evidence sources: GLM benchmark runs (truncated files, missing zeroize, compliance-theater helpers, the 88.85→97.00 hostile-self-review delta) and two nuri-expo commit reviews (ed60764b: constructor-registered listener leaked per transient instance; 51d1306f: comment described unimplemented code, Promise.all let a secondary keychain read block unlock).

Trade-off: DB-connection-caching rule dropped. The original draft had a rule about connection caching, but the 1→N failure-semantics rule (from 51d1306f) had stronger evidence. The weaker rule lost its slot per the cap policy.

2026-07-05 · 4d5b921 — Fix Worker transport

What: Switched the Worker from StreamableHTTPServerTransport to WebStandardStreamableHTTPServerTransport.

Why: The Node.js StreamableHTTPServerTransport depends on @hono/node-server which requires Node stream and crypto builtins not available in the Cloudflare Workers runtime. The MCP SDK ships WebStandardStreamableHTTPServerTransport specifically for web-standard environments (Workers, Deno, Bun). Switched to that in stateless mode (no session ID). Worker is now live and serving rules over MCP-over-HTTP.

2026-07-08 — Documentation discipline rule + Worker bugfix

What: Three changes:

1. Global rule 16: every non-obvious decision, bug root-cause, or design trade-off must be documented in README.md
2. Bugfix: Worker was missing coding rules — only served global and tooling
3. Selfcheck extended to prevent Worker divergence mechanically

Why (rule 16): Emin wanted the README to be the product's memory. When work is handed off to another developer or agent, they should read one file and understand the entire development history — what was built, why, what alternatives were considered, what mistakes were made and how they were fixed.

Why (Worker bugfix): The coding rules were added to src/index.mjs in commit 632ec23 but the Worker (src/worker.mjs) was never updated. Agents connecting via HTTP got incomplete instructions. Root cause: two entry points with no automated sync check.

Decision: README as single source of truth. Previously the README was a standard project readme and a separate FAQ.md held decisions. Emin decided to merge everything into the README: development journal, architecture decisions, mistakes, Q&A. One file. Anyone reading it gets the full picture.

Decision: Mechanical prevention of Worker divergence. Selfcheck now reads src/worker.mjs and asserts it imports and registers every rule set. Add a rule to index.mjs → selfcheck fails until you also add it to worker.mjs.

2026-07-16 — v0.2.0: Mechanical rule enforcement (4 tools + SDK)

What: Four MCP tools that mechanically enforce the rules, plus a client SDK. Selfcheck extended from 34 to 65 assertions.

Why: The rules were instructions agents read but could ignore. Till Kolter's guck-mcp showed the pattern: MCP tools that do real work, not just recite text. The highest-leverage move was adding tools that verify rules were followed.

New tools:

Tool	Enforces	What it checks
scope_check	Rule #3: scope drift = stop	Files/LOC planned vs. actual. 1.5x file threshold, 2x LOC threshold.
secrets_check	Rule #14: never commit secrets	12 regex patterns: OpenAI keys, GitHub tokens, AWS keys, private keys, mnemonics, ETH keys, JWTs, passwords. Redacts findings.
rule_check	Rules #5, #6, #9, #10	Unsafe casts (as any, !), silent fallbacks, missing zeroize, compliance-theater comments.
handoff	Tooling rule #6: subagent delegation	Validates handoff context: has done items? has next action? notes too long?

Decision: Compact syntax on every tool. Following Till's pattern, every tool accepts short-key aliases (fp for files_planned, t for text, p for path). Saves ~30% tokens on tool call arguments.

Decision: Zod schemas, not plain JSON. The MCP SDK requires Zod schema objects for inputSchema. Switched all four tools from plain JSON Schema to z.object({...}).

Decision: Client SDK (src/sdk/index.mjs). Agents can import the check functions directly without MCP transport. checkAll({ diff, path, plan }) runs scope + secrets + rules in one call. validateHandoff(to, context) validates handoff structure. Same logic, no network dependency.

Decision: Tool responses as JSON strings in content[0].text. The MCP SDK wraps tool output in { content: [{ type: "text", text: "..." }] }. Selfcheck parses this with a parseResult() helper.

Mistake: Regex syntax errors. First pass used (?i) inline flags which aren't valid in JS regex literals. Switched to /gi suffix. Also the OpenAI key regex /sk-[A-Za-z0-9]{20,}/ didn't match sk-proj-... because of hyphens — fixed to /sk-[A-Za-z0-9\-]{20,}/.

Mistake: Plain JSON Schema rejected by MCP SDK. The SDK's getZodSchemaObject throws on non-Zod objects. Had to rewrite all schemas with z.object().

What's next: Deploy to Cloudflare Worker. Add scope_check to the agent's pre-commit flow. Consider a secrets_check git hook.

2026-07-16 — v0.2.0 cleanup: architecture, CI/CD, auto-deploy

What: Refactored to match Till Kolter's MCP design patterns. Added CI/CD. Selfcheck: 65 → 95 assertions.

Why: The previous structure had three problems:

1. index.mjs + worker.mjs duplicated 50 lines of registration
2. SDK imported from tools/ → pulled in Zod + MCP response format
3. No auto-deploy, no CI — every push needed manual wrangler deploy

New architecture (Till's pattern):

src/
├── index.mjs          # Stdio entry — 8 lines
├── worker.mjs         # HTTP entry — 12 lines
├── server.mjs         # createServer() — shared registration
├── version.mjs        # Single VERSION constant
├── rules/             # Static rule text (unchanged)
├── checks/            # Pure functions — zero deps
│   ├── scope.mjs      # checkScope()
│   ├── secrets.mjs    # checkSecrets()
│   ├── rules.mjs      # checkRules()
│   └── handoff.mjs    # checkHandoff()
├── tools/             # MCP wrappers — Zod schemas, call checks/
│   ├── scope_check.mjs
│   ├── secrets_check.mjs
│   ├── rule_check.mjs
│   └── handoff.mjs
└── sdk/
    └── index.mjs      # Imports from checks/ — zero deps

Decision: Three-layer architecture. checks/ = pure logic (no MCP, no Zod). tools/ = MCP wrappers (Zod schemas, content[0].text format). sdk/ = client library (imports from checks/, zero deps). Add a check → add to checks/, wrap in tools/, re-export in sdk/. Selfcheck enforces this mechanically.

Decision: createServer() in server.mjs. Single source of truth for resource + tool registration. Both index.mjs (stdio) and worker.mjs (HTTP) call createServer(). Add a resource or tool → add it to server.mjs once. Selfcheck asserts neither entry point does direct registration.

Decision: version.mjs. Single VERSION constant imported by server.mjs. No more duplicated version strings across files.

Decision: Auto-deploy on push to master. .github/workflows/deploy.yml: checks out, installs, runs selfcheck, deploys via cloudflare/wrangler-action. Needs CLOUDFLARE_API_TOKEN secret in GitHub repo settings.

Decision: CI on PRs. .github/workflows/ci.yml: runs selfcheck on every PR and on pushes to non-master branches. Catches regressions before merge.

What you need to do (one-time):

1. Go to https://github.com/eminogrande/emin/settings/secrets/actions
2. Add CLOUDFLARE_API_TOKEN — get it from npx wrangler whoami or Cloudflare dashboard
3. That's it. Every push to master auto-deploys.