efaimo 0.1.0

package/dist/weigh/weigh.js

@@ -0,0 +1,104 @@
+import { countClaudeToolTokens } from "./anthropicExact.js";
+import { serializeClaudeStyle, serializeOpenAITools, serializeRawJson, serializeSingle } from "./serializers.js";
+import { loadTokenizer } from "./tokens.js";
+import { isBinaryPath, readTextSafe } from "../util/misc.js";
+export async function weighServer(intro, opts = {}) {
+    const count = await loadTokenizer();
+    const perTool = [];
+    for (const tool of intro.tools) {
+        const s = serializeSingle(tool);
+        perTool.push({
+            name: tool.name,
+            tokens: {
+                rawJson: count(s.rawJson),
+                claudeStyle: count(s.claudeStyle),
+                openaiTools: count(s.openaiTools),
+            },
+            descriptionTokens: count(tool.description ?? ""),
+            schemaTokens: count(JSON.stringify(tool.inputSchema ?? {})),
+        });
+    }
+    perTool.sort((a, b) => b.tokens.claudeStyle - a.tokens.claudeStyle);
+    const totals = {
+        rawJson: count(serializeRawJson(intro.tools)),
+        claudeStyle: count(serializeClaudeStyle(intro.tools)),
+        openaiTools: count(serializeOpenAITools(intro.tools)),
+    };
+    // Per-tool rows count each tool's bare definition line; the total counts the
+    // <functions> block around them. Report the wrapper explicitly so the rows
+    // reconcile with the total (clamped: tokenizer merges across boundaries can
+    // in principle make the residual negative on other serializations).
+    const framingTokens = Math.max(0, totals.claudeStyle - perTool.reduce((s, t) => s + t.tokens.claudeStyle, 0));
+    const notes = [
+        "token counts are estimates using the o200k_base tokenizer; hosts add fixed framing text on top (see docs/METHODOLOGY.md)",
+    ];
+    let anthropicExactTotal;
+    if (opts.anthropicApiKey && intro.tools.length > 0) {
+        anthropicExactTotal = await countClaudeToolTokens(intro.tools, {
+            apiKey: opts.anthropicApiKey,
+            model: opts.anthropicModel,
+        });
+        if (anthropicExactTotal !== undefined) {
+            notes.push("anthropic-exact measured via /v1/messages/count_tokens (tools delta)");
+        }
+        else {
+            notes.push("anthropic-exact measurement failed; showing o200k estimates only");
+        }
+    }
+    return {
+        kind: "mcp",
+        label: intro.targetLabel,
+        toolCount: intro.tools.length,
+        resourceCount: intro.resources.length,
+        promptCount: intro.prompts.length,
+        perTool,
+        totals,
+        framingTokens,
+        instructionsTokens: count(intro.instructions ?? ""),
+        anthropicExactTotal,
+        notes,
+    };
+}
+export async function weighSkills(set) {
+    const count = await loadTokenizer();
+    const perSkill = [];
+    for (const skill of set.skills) {
+        const name = skill.name ?? "(unnamed)";
+        const metadataTokens = count(`${name}: ${skill.description ?? ""}`);
+        const bodyTokens = count(skill.body);
+        let refFileTokens = 0;
+        let refFileCount = 0;
+        for (const ref of skill.referencedPaths) {
+            if (!ref.exists || isBinaryPath(ref.resolved))
+                continue;
+            const text = readTextSafe(ref.resolved);
+            if (text === undefined)
+                continue;
+            refFileCount++;
+            refFileTokens += count(text);
+        }
+        perSkill.push({
+            name,
+            dir: skill.dir,
+            metadataTokens,
+            bodyTokens,
+            bodyLines: skill.bodyLines,
+            refFileCount,
+            refFileTokens,
+        });
+    }
+    return {
+        kind: "skill",
+        label: set.root,
+        perSkill,
+        totals: {
+            metadata: perSkill.reduce((s, x) => s + x.metadataTokens, 0),
+            body: perSkill.reduce((s, x) => s + x.bodyTokens, 0),
+            refFiles: perSkill.reduce((s, x) => s + x.refFileTokens, 0),
+        },
+        notes: [
+            "metadata loads at session start for every installed skill; body loads on trigger; referenced files load on demand",
+            "token counts are o200k_base estimates (see docs/METHODOLOGY.md)",
+        ],
+    };
+}

package/docs/INTEGRATIONS.md

@@ -0,0 +1,119 @@
+# Integrating efaimo
+
+efaimo is a plain CLI, so it drops into anything that can run a command. This is the
+practical guide, from local dev to CI to calling it from an agent.
+
+## Local: pre-commit
+
+Stop a broken skill before it lands. `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: efaimo-skills
+        name: efaimo check --skill
+        entry: npx efaimo check --skill ./skills --strict
+        language: system
+        pass_filenames: false
+        files: ^skills/.*SKILL\.md$
+```
+
+## CI: GitHub Actions
+
+Fail the build on skill regressions or a context-budget blowout.
+
+```yaml
+- uses: efaimo-ai/efaimo@v0
+  with:
+    command: check --skill ./skills --strict
+```
+
+Ratchet MCP tool-definition cost with the budget gate (commit `base.json` once with
+`npx efaimo weigh "npx -y your-server" --out base.json`):
+
+```yaml
+- run: npx efaimo weigh "npx -y your-server" --diff base.json --allow-increase 10
+```
+
+Post the grade on the PR with `--md` (pipe into any comment action):
+
+```yaml
+- run: npx efaimo check --skill ./skills --md >> "$GITHUB_STEP_SUMMARY"
+```
+
+## CI: GitLab
+
+```yaml
+efaimo:
+  image: node:24
+  script:
+    - npx efaimo check --skill ./skills --strict
+    - npx efaimo weigh "npx -y your-server" --diff base.json --allow-increase 10
+```
+
+## Audit what an editor already loads
+
+efaimo reads the MCP config of the tools you already use and weighs everything they
+load, so you can see the context tax before you open a chat:
+
+```bash
+npx efaimo weigh --client claude-code      # also: claude-desktop, cursor, vscode
+```
+
+## Use it as an Agent Skill
+
+efaimo ships a `SKILL.md`, so an agent that supports Agent Skills can install it and
+run the checks itself:
+
+```bash
+npx skills add efaimo-ai/efaimo
+```
+
+The skill is a thin trigger; the `npx efaimo` binary does the work. It pairs with
+`skills validate` (metadata) as the deeper tier (quality, cost, collisions, and the
+`test` A/B harness): `npx skills validate ./skill && npx efaimo check --skill ./skill`.
+
+## Cursor / VS Code / Windsurf
+
+Any editor that runs tasks can run efaimo. Add a task or a keybinding to
+`npx efaimo check --skill ${workspaceFolder}/skills`, and use `weigh --client cursor`
+(or `vscode`) to audit the MCP servers that editor loads.
+
+## Calling efaimo from an agent (efaimo mcp)
+
+`efaimo mcp` runs efaimo as a small, read-only MCP server over stdio. It exposes two
+tools, `efaimo_check_skill` and `efaimo_weigh_skill`, so an agent can lint or weigh a
+skill mid-session, before it commits it to context. The tools read files only: they
+spawn no process, open no socket, and `test` (which spends tokens) is not exposed, so
+the server is safe to call unattended.
+
+Add it to a client config (Claude Desktop, Claude Code, Cursor, ...):
+
+```json
+{
+  "mcpServers": {
+    "efaimo": { "command": "npx", "args": ["-y", "efaimo", "mcp"] }
+  }
+}
+```
+
+Both tools take a `path` to a SKILL.md or a folder of skills and return Markdown.
+
+efaimo holds its own server to the same bar. `efaimo check --mcp "npx -y efaimo mcp"`
+grades it a quality A with a three-item 2026-07-28 migration diff: a fully
+stateless server wants the 2.x MCP SDK for `server/discover`, cache fields, and
+`resultType`. That SDK upgrade is the roadmap item; the server is useful today on
+the current SDK.
+
+## Programmatic use
+
+Every capability is also a typed function:
+
+```ts
+import { weighServer, introspectServer, checkSkillSet } from "efaimo";
+
+const intro = await introspectServer({ kind: "stdio", command: "npx", args: ["-y", "my-server"], label: "my-server" });
+const cost = await weighServer(intro);
+console.log(cost.totals.claudeStyle);
+```

package/docs/METHODOLOGY.md

@@ -0,0 +1,83 @@
+# How efaimo counts tokens
+
+efaimo's numbers are meant to be **reproducible and honest**, not authoritative
+down to the token. This document is the whole method so you can check it.
+
+## The tokenizer
+
+Estimates use **OpenAI's `o200k_base`** tokenizer (via `gpt-tokenizer`), because
+it is public, deterministic, runs offline, and tracks the vocabularies of current
+frontier models closely on English and JSON. Every estimated number in efaimo's
+output is labeled `o200k` / `estimated`.
+
+Different hosts use different tokenizers, and no vendor tokenizer but OpenAI's is
+public, so the estimate carries an **unmeasured, consistent bias** against any
+specific host. That makes it reliable for **comparison** (bias cancels in a
+`--diff`, so budget gates are trustworthy) but only **approximate in absolute
+terms**: the absolute thresholds (E127, E128) and the "percent of window" figure
+can be off by more than a few percent, and should be read as order-of-magnitude,
+not billing. When you need Claude-exact numbers, pass `--anthropic` (see below).
+A calibration study across real schemas is future work; until then the default is
+labeled an estimate precisely because its absolute accuracy is unverified.
+
+## What we serialize
+
+A tool definition's real cost depends on how a host serializes it into the model's
+context. efaimo reports three serializations so you can see the spread:
+
+- **raw JSON** - the `tools/list` payload, minified. A neutral lower bound.
+- **Claude-style** - each tool as `{"description","name","parameters"}` wrapped in
+  a `<functions>` block, mirroring how Claude-family harnesses present tools. This
+  is efaimo's **primary metric** (the one used for badges, diffs, and budgets)
+  because it is the closest public approximation of a real system-prompt injection.
+- **OpenAI tools** - the Chat Completions `tools` array shape.
+
+Hosts wrap these in a small amount of fixed framing text (headers, instructions on
+how to call tools). That framing is **per-host constant** and independent of your
+server, so efaimo excludes it: it would add the same number to every server and
+wash out of any comparison or diff.
+
+### Per-tool numbers vs the total
+
+Per-tool numbers count each tool's **bare definition line**; the Claude-style
+total counts the whole `<functions>` block, including the `<function>` tags and
+newlines around every line. That wrapper is reported as its own **block framing**
+line item, so per-tool numbers plus framing equal the Claude-style total. The
+per-tool threshold rule (E127) uses the bare line; the total rule (E128) uses the
+wrapped total. For the other two serializations no wrapper exists, and summing
+per-tool counts may differ from the total by a few tokens, because a tokenizer
+can merge characters across element boundaries when tools are concatenated.
+
+## Skills
+
+For Agent Skills efaimo reports the three progressive-disclosure levels defined by
+the spec separately, because they load at different times:
+
+- **metadata** (`name` + `description`) - loaded at session start for *every*
+  installed skill. This is the always-on cost; the spec targets ~100 tokens.
+- **body** - the rest of `SKILL.md`, loaded when the skill triggers.
+- **referenced files** - `references/`, `scripts/`, `assets/` linked from the body,
+  loaded only on demand.
+
+## Claude-exact mode
+
+With `--anthropic` (and `ANTHROPIC_API_KEY` set), efaimo also calls Anthropic's
+`POST /v1/messages/count_tokens`, which accepts a `tools` array, and measures the
+**delta** between a request with your tools and the same request without them. That
+delta is the exact number of tokens your tool definitions add for the chosen Claude
+model. This requires network and a key, so it is opt-in; the o200k estimate is
+always shown alongside.
+
+## Determinism
+
+Given the same server output, efaimo produces the same numbers every run: the
+tokenizer is deterministic and no sampling is involved. Server responses can change
+between runs (a server may reorder or add tools); efaimo's `check` flags
+nondeterministic `tools/list` ordering (E112) precisely because it affects both
+prompt-cache hits and reproducibility.
+
+## What this is not
+
+efaimo estimates the **cost of tool/skill definitions sitting in context**. It does
+not measure per-call argument/result tokens, host framing, or model-side reasoning.
+For end-to-end token accounting, instrument your agent run directly.

package/docs/RULES.md

@@ -0,0 +1,76 @@
+# efaimo rules
+
+Every finding carries a stable rule id so you can suppress, track, or link it.
+Severities: **error** (will bite you), **warn** (should fix), **info** (worth knowing).
+
+Grade starts at 100; each error costs 15, each warning 5, each info 1.
+`A >= 90, B >= 80, C >= 70, D >= 60, else F`.
+
+MCP checks split into **2026-07-28 readiness** (E101-E118) and **quality**
+(E121-E130); skill checks are S1xx. **Only quality and skill findings are
+graded.** Readiness findings are reported as a separate, ungraded **migration
+diff**: the stateless revision they target is a locked Release Candidate
+(2026-05-21) that does not finalize until 2026-07-28, and not yet migrating to
+an unreleased spec is a to-do, not a defect. Readiness severities still order
+the diff by urgency, but the diff never affects the grade, the badge, or the
+exit code (including `--strict`). Once the spec ratifies, expect readiness to
+start counting in a minor release. Source-pattern rules are heuristics and say
+so in their detail line.
+
+## MCP readiness (E101-E118)
+
+| id | sev | what it catches | source of truth |
+|---|---|---|---|
+| E101 | warn | depends on a pre-`2026-07-28` SDK line (TS `@modelcontextprotocol/sdk` 1.x, Python `mcp` 1.x) instead of the 2.x stateless line | changelog / SDK releases |
+| E102 | warn | source uses **Sampling** (`sampling/createMessage`), deprecated (SEP-2577) | draft changelog |
+| E103 | warn | source uses **Roots** (`roots/list`), deprecated (SEP-2577) | draft changelog |
+| E104 | warn | server declares the **logging** capability or source uses MCP Logging, deprecated (SEP-2577); `logging/setLevel` is removed | draft changelog |
+| E105 | warn | the server does not answer a bare stateless `tools/list` (timeout, crash, or a not-initialized error), so it requires the removed `initialize` handshake. A server that answers (even with an error) is judged by E106/E107/E118 instead | SEP-2567 / stateless core |
+| E106 | warn | `server/discover` is not implemented (MUST in the RC, SEP-2575) | draft changelog |
+| E107 | info | results omit the required `resultType` field (`"complete"` \| `"input_required"`) | draft changelog |
+| E108 | info | source relies on removed SSE resumability (`Last-Event-ID`) | draft changelog |
+| E109 | info | auth advertises deprecated DCR (RFC 7591) with no detected CIMD support | PR #2858 / CIMD |
+| E110 | warn | source uses legacy elicitation (`elicitation/create`); replaced by MRTR `input_required` results (SEP-2322) | draft changelog |
+| E111 | info | in-process session-state patterns; statelessness expects server-minted handles in tool args | stateless core |
+| E112 | warn | `tools/list` order is nondeterministic across connections (hurts prompt-cache hits) | draft changelog |
+| E113 | info | no Server Card found at `/.well-known/mcp` (discovery metadata; heuristic path) | roadmap / Server Card WG |
+| E114 | info | source uses the removed `ping` utility | draft changelog |
+| E115 | info | source uses `resources/subscribe`, replaced by `subscriptions/listen` | draft changelog |
+| E116 | warn | server prints non-JSON noise on stdout (breaks stdio framing) | transport basics |
+| E117 | warn | only the deprecated HTTP+SSE transport worked; Streamable HTTP failed | draft changelog |
+| E118 | warn | `tools/list` result omits the now-required `ttlMs`/`cacheScope` cache fields (SEP-2549, CacheableResult; also required on prompts/list, resources/list, resources/read, resources/templates/list, server/discover) | draft changelog |
+
+## MCP quality (E121-E130)
+
+| id | sev | what it catches |
+|---|---|---|
+| E121 | error/warn | tool description missing, a placeholder, or under ~20 chars |
+| E122 | warn | description misses 3+ of 4 quality axes (length, when-to-use, params documented, mentions result), mirrors Glama's tool-definition-quality dimensions, computed locally |
+| E123 | warn/info | no tools declare annotations; a destructive-looking tool lacks `destructiveHint` |
+| E124 | warn | many undocumented parameters, or an oversized `enum` inflating every prompt |
+| E125 | warn | tool count high enough (30+, 60+) to degrade routing and inflate context |
+| E126 | warn/info | tool names mix conventions or exceed 64 chars |
+| E127 | warn | a single tool definition costs 800+ tokens (needs `weigh` data) |
+| E128 | warn | total tool-definition tax over ~10k / ~25k tokens, estimated (needs `weigh` data); hard CI failure is left to the `--max-tokens`/`--diff` gate |
+| E130 | info | instruction-injection patterns in a tool description or server instructions (shallow heuristic, never a security verdict; use a dedicated scanner for depth) |
+
+## Skills (S101-S106)
+
+| id | sev | what it catches | spec |
+|---|---|---|---|
+| S101 | error/warn/info | frontmatter invalid: missing `name`/`description`, `name` not matching the directory, over length limits, `metadata` not a string map, non-standard fields | agentskills.io |
+| S102 | warn/info | description too thin or never says when to use the skill | agentskills.io |
+| S103 | error/warn | duplicate skill names, or two skills with heavily overlapping descriptions (trigger collision) | internal |
+| S104 | warn/info | metadata over ~100 tokens, body over ~5k tokens or 500 lines, or long body with no progressive disclosure | agentskills.io |
+| S105 | info | instruction-injection patterns in the skill body or description (shallow heuristic, never a security verdict) | internal |
+| S106 | error/warn/info | referenced file missing, escaping the skill dir (`..`), or nested more than one level deep | agentskills.io |
+
+## Notes on heuristics
+
+Rules that scan **source code** (E101-E104, E108, E110, E111, E114, E115) are
+pattern matches over your repo and can produce false positives; each finding says
+so and points at the file:line so you can confirm. Rules that scan **a live
+server** (E105-E107, E112, E116, E117) and the token rules (E127, E128) reflect
+what the server actually did. `efaimo` is a linter, not a security scanner:
+E130/S105 are surface heuristics, for real supply-chain security use a dedicated
+tool such as Snyk agent-scan or the Cisco MCP Scanner.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "efaimo",
+  "version": "0.1.0",
+  "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent-skills",
+    "skills",
+    "audit",
+    "lint",
+    "tokens",
+    "context-window",
+    "claude",
+    "ai-agents",
+    "cli"
+  ],
+  "license": "Apache-2.0",
+  "author": "efaimo ai <hello@efaimo.ai> (https://efaimo.ai)",
+  "homepage": "https://github.com/efaimo-ai/efaimo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/efaimo-ai/efaimo.git"
+  },
+  "bugs": "https://github.com/efaimo-ai/efaimo/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "efaimo": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "NOTICE",
+    "CHANGELOG.md",
+    "docs/METHODOLOGY.md",
+    "docs/RULES.md",
+    "docs/INTEGRATIONS.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^15.0.0",
+    "cross-spawn": "^7.0.6",
+    "gpt-tokenizer": "^3.4.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}