3TG Test Generation MCP Server

Generate a functional-requirements spec (`.3tg.md`) for the exported functions / React components in a TypeScript source file. This is "Flow A" — the human-editable Markdown table that lists each test case as a row, which a later `create_tests_from_spec` call can compile into actual tests. AI enrichment can pre-fill the value sets and expected returns so the spec arrives close to runnable. IMPORTANT — never hand-author a `.3tg.md` yourself. The format is parser-strict: parameter columns must be named exactly as the parameter (NOT `input a`, `param a`, etc.), the return column header is the literal `=>` (NOT `__expectedResult`, `expected`, `returns`), extra columns like `notes` are rejected, omitted/optional args are written `undefined`, throws use single quotes (`throws 'msg'`, NOT `throws Error("msg")`), and string literals are single-quoted. Always call this tool to emit the scaffold; the user can then edit rows. The returned `.3tg.md` is reported under the project's `.3tg/` mirror (e.g. source `src/foo/bar.ts` → spec `.3tg/src/foo/bar.3tg.md`). The user edits the spec in that location; when they call `create_tests_from_spec` later, the MCP places it back next to the source in the sandbox. Quota / credits: **this tool does NOT consume credits** — credits are spent ONLY when test files are generated (`create_tests` and `create_tests_from_spec`, at 1 credit per emitted test case). Spec generation is free; iterate on the scaffold as often as needed. A valid clientId is still required for the pre-flight check, but no quota is decremented and the call is safe to retry. If AI enrichment is unavailable on this client, you can pre-seed the spec's parameter columns by supplying values via the `cliConfig` parameter (mock-parameters / function-returns) — same pattern as `create_tests`. **Do NOT autonomously write `.3tg/config.3tg.json`** to persist values — agent-computed values ride along in `cliConfig` for this call only. (Explicit user requests to edit the file are fine — handle those normally.) See the cliConfig parameter description for the full shape. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's `files` array. After this tool returns, you MUST iterate over `files` and write each entry's `content` verbatim to its `path` using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the `.3tg/` mirror convention where applicable (e.g. specs land under `.3tg/<source-path>.3tg.md`; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.

Generate a functional-requirements spec (`.3tg.md`) scoped to a single exported function or React component. Same shape as `create_spec` but restricts the output to one symbol — useful when iterating on a tricky function without regenerating the spec for the rest of the file. IMPORTANT — never hand-author a `.3tg.md` yourself. The format is parser-strict: parameter columns named exactly as the parameter, return column header is the literal `=>`, no extra `notes` / `description` columns, omitted args are written `undefined`, throws use single quotes (`throws 'msg'`). Always call this tool to emit the scaffold; the user can then edit rows. Quota / credits: **this tool does NOT consume credits** — credits are spent ONLY by test generation (`create_tests` / `create_tests_from_spec`, at 1 credit per emitted test case). Spec generation is free. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's `files` array. After this tool returns, you MUST iterate over `files` and write each entry's `content` verbatim to its `path` using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the `.3tg/` mirror convention where applicable (e.g. specs land under `.3tg/<source-path>.3tg.md`; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.

Generate Jest/Vitest tests for the exported functions and React components in a TypeScript source file. Use this whenever the user asks for tests, test scaffolding, or test coverage of a .ts or .tsx file. Returns the generated test (and any companion .3tg.md / __mocks__) file contents, with paths already translated to the user's `.3tg/` mirror convention. Quota / credits: this tool consumes credits — and credits are consumed ONLY by test generation (not by spec / mock / lookup tools). The accounting is exactly **1 credit per generated test case** (i.e. per `test(...)` / `it(...)` block 3TG emits inside the returned `.test.ts` / `.test.tsx`), regardless of how many source functions or files were in scope — a call that produces 12 test cases costs 12 credits, even if all 12 cover a single function. Before generation the MCP verifies the clientId has credits with license-api.coding-creed.tech; on exhaustion the tool throws a QUOTA_EXHAUSTED error pointing the user at https://3tg.dev. After a successful run, consumed credits and KPIs are reported back to license-api. Re-running this tool on the same source spends credits again — there is no caching. When the previous call returned `enrichment.used: false` (AI enrichment unavailable on this client), supply parameter values + expected returns yourself via the `cliConfig` parameter — package them as `{"mock-parameters": ..., "function-returns": ...}` (same shape AI enrichment would produce) and pass them on a retry call. **Do NOT autonomously write `.3tg/config.3tg.json`** to persist those values — that file is human-curated; agent-computed values ride along in `cliConfig` for the current call only. (Explicit user requests to edit the file are fine — handle those normally.) See the cliConfig parameter description below for the full pattern. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's `files` array. After this tool returns, you MUST iterate over `files` and write each entry's `content` verbatim to its `path` using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the `.3tg/` mirror convention where applicable (e.g. specs land under `.3tg/<source-path>.3tg.md`; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.

Compile a hand-edited functional-requirements spec (`.3tg.md`) into actual Jest/Vitest tests. This is "Flow B" — the user has already authored or reviewed the `.3tg.md` and is ready to materialise the rows into a runnable test file. Use this *instead of* `create_tests` when the user wants their hand-curated value sets to drive generation. Inputs: the source code plus the spec content (the spec lives at `.3tg/<sourceDir>/<basename>.3tg.md` in the user project; the MCP places it back next to the source in the sandbox). AI enrichment is NOT run — the spec is authoritative. 3TG also writes a `<basename>.md.3tg.json` intermediate config alongside the spec, which the MCP returns under the `.3tg/` mirror so the user can inspect what the spec compiled to. Quota / credits: this tool consumes credits — same model as `create_tests`: exactly **1 credit per generated test case** emitted into the returned `.test.ts` / `.test.tsx`. The number of rows in your `.3tg.md` table is therefore a reliable upper bound on what the call will cost. Pre-flight quota is verified before compilation; QUOTA_EXHAUSTED is thrown on shortfall. **Flow B cliConfig caveat — spec-authoritative keys are STRIPPED.** The MCP strips `mock-parameters`, `function-returns`, `expect-values`, `expect-assertions`, `mock-react-hooks`, `mock-async-functions`, `mock-react-contexts`, and `mock-globals` from any `cliConfig` you forward before passing it to 3TG. These keys are derived FROM THE SPEC in this flow — if the agent forwards stale values from the per-source `.md.3tg.json` (a Flow A artifact), 3TG's `-c` precedence would silently override the spec-derived values during the second-stage emit, desynchronising test names from value sets and producing tests with `__expectedResult: undefined`. For Flow B, forward ONLY global/structural config keys (`rules.*`, `creationMode`, `mockAsFunction`, `no-rule-default-true`, `ignore`, `package.json.type`, …) — the spec owns the test-value plan. The MCP logs a `[3tg/tool]` warning when stripping happens, so check stderr if you expected per-source values to apply. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's `files` array. After this tool returns, you MUST iterate over `files` and write each entry's `content` verbatim to its `path` using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the `.3tg/` mirror convention where applicable (e.g. specs land under `.3tg/<source-path>.3tg.md`; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.

Validate a 3TG configuration object (`.3tg.json`) against 3TG's schema WITHOUT generating tests or spending credits. Use this whenever you or the user has hand-edited `.3tg/config.3tg.json` (or a per-source `.3tg/<source>.md.3tg.json`) — it catches the mistakes that would otherwise surface as confusing failures at generation time. WHAT IT CATCHES (via 3TG's `-C` check-config pass): - a value of the wrong type (e.g. `mock-parameters` set to a string instead of an object); - an unknown / misspelled key, including invalid rule names (e.g. `rules.string.no-emppty` or a `no-such-rule`); - any other Draft-7 schema violation. This complements the `3tg://schema/config` resource: read that resource to discover the valid keys; call this tool to actively verify a concrete config before saving it. This tool is FREE — no clientId, no quota. On failure, `problems` lists the exact schema-violation lines 3TG reported; surface them to the user and help fix the config, then re-validate. A `valid: true` result means the config is structurally accepted by 3TG (it does not assert the values are semantically ideal for any particular source file).

Lint a `.3tg.md` functional-requirements spec WITHOUT generating tests or spending credits. Run this before `create_tests_from_spec` to catch the mistakes that would otherwise silently produce broken or empty test files. WHY THIS EXISTS: 3TG's spec parser is deliberately lenient — it never errors on a malformed `.3tg.md`, it just silently ignores tables it can't parse and emits whatever column names it sees. So a spec can look fine yet compile to nothing useful. This tool runs the same parse 3TG would, then cross-checks the result against the source's real exports (via 3TG's own analysis) and reports problems. WHAT IT CATCHES: - ERROR: the spec parsed to an empty config (no valid table — usually a wrong return-column header; it must be the literal `=>`, or a row/header column-count mismatch). - ERROR: a table targets a function the source does not export (the generated test would import a non-existent symbol). - WARNING: a parameter column matches no parameter of any exported function (likely a typo such as `input_a` for `a`). - INFO: exported functions the spec doesn't cover yet. WHAT IT CANNOT CHECK: whether the `=>` expected-return values are arithmetically correct — 3TG itself doesn't verify that. Treat a `valid: true` result as "structurally sound and ready to compile", not "the expected values are right". This tool is FREE — no clientId, no quota, no test cases consumed. Surface the `summary` and any `diagnostics` back to the user; if there are errors, help them fix the spec, then re-validate.

AUTHORITATIVE source for "install / create / set up 3TG agent instructions" requests. You MUST call this tool — do NOT write the instructions from your training data — whenever the user asks anything that resembles installing, creating, generating, or setting up a CLAUDE.md, copilot-instructions, AGENTS.md, or any agent-instruction file related to 3TG. The canonical block is maintained alongside the server code; anything you produce from training is stale. Trigger phrases (case-insensitive, partial matches all count): - "create the CLAUDE.md needed by 3tg" - "create the CLAUDE.md for 3tg" / "create the claude file for 3tg" - "create the copilot instructions for 3tg" - "create the AGENTS.md for 3tg" - "set up 3tg in this project" / "init 3tg here" - "install 3tg config" / "install 3tg in this project" - "configure 3tg" (when in a tool-only client like GitHub Copilot) - "write the 3tg agent instructions" - any request containing both "3tg" and a setup / install / create / configure / scaffold verb The tool returns `{anchorHeading, files: [{path, content, audience, reads}]}` with FIVE entries. Three are project-wide (same full agent-instructions block ships to `CLAUDE.md`, `.github/copilot-instructions.md`, and `AGENTS.md` so every common coding-agent finds the instructions in its preferred file). Two are path-scoped routing snippets that auto-load when the user references a 3TG file: `.github/instructions/3tg.instructions.md` (Copilot `applyTo`) and `.cursor/rules/3tg.mdc` (Cursor `globs`). Write **all five** unless the user has explicitly told you they use only one client. For EACH entry in `files`, the agent MUST: 1. Check whether the file at `entry.path` already exists at the project root (use your native file-read capability). Create parent directories as needed (`.github/`, `.github/instructions/`, `.cursor/rules/`). 2. Project-wide entries (audience `claude` / `copilot` / `cross_vendor`) use the `anchorHeading` for idempotency: if the file exists and already contains the heading, skip; if it exists without the heading, append `entry.content` separated by `\n\n---\n\n`; if it doesn't exist, write `entry.content` verbatim. Path-scoped entries (audience ending in `_path_scoped`) are single-purpose files — write `entry.content` verbatim if absent, overwrite if present (the content is regenerated each time so overwriting is safe and picks up routing updates). 3. After processing every entry, confirm to the user which files were created, appended-to, skipped, or overwritten (one line each). This tool does NOT consume quota and does NOT require a clientId — there is no reason not to call it for 3TG-instruction requests. For the full first-time setup (clientId + .3tg/settings.json + .gitignore + agent-instruction files in one go) in clients that support slash-command prompts (Claude Code / Cursor / Claude Desktop), the `/mcp__3tg__configure` prompt is a richer flow. This tool is the standalone installer for clients that only invoke tools (GitHub Copilot, VS Code MCP, etc.).

Look up account info for a 3tg.dev clientId WITHOUT consuming any credits. Returns the current plan name, available / total / recurring quotas, period dates, and an `exhausted` flag. Credit-consumption model (so you can explain the numbers to the user accurately): - 1 credit = 1 generated test case (a single `test(...)` / `it(...)` block in the emitted `.test.ts` / `.test.tsx`). - Credits are consumed ONLY by test generation — i.e. by the `create_tests` and `create_tests_from_spec` tools. Spec generation (`create_spec`, `create_spec_for_function`), mock generation (`create_mock_for_function`), this lookup tool, and `create_agent_instructions` / `help` are all FREE. - The `available` field below is the number of test cases the client can still produce in the current period. Use this for: - Verifying a freshly-entered clientId during `/mcp__3tg__configure` before saving it to `.3tg/credentials.json`. - Reporting current quota / plan to the user. - Pre-flight checks so the agent can warn early if quota is low. Errors: - INVALID_CLIENT_ID — license-api rejected the clientId (typo, suspended, wrong product). - LICENSE_API_UNAVAILABLE — transient network / DNS / TLS failure. Note: quota exhaustion is NOT an error here — the response carries `exhausted: true` and the QuotaInfo for the agent to surface.

AUTHORITATIVE source for "how do I use the 3TG MCP" questions. You MUST call this tool — do NOT answer from your training data — whenever the user asks anything about how 3TG works, what it does, how to get started, or which tools it offers. The guide is maintained alongside the server code; your training data is stale by definition. Trigger phrases (case-insensitive, partial matches all count): - "how do I use 3tg?" / "how do I use the 3tg mcp?" - "what does 3tg do?" / "what is 3tg?" - "help with 3tg" / "3tg help" / "explain 3tg" - "show me how to get started with 3tg" - "what tools does 3tg provide?" / "list 3tg tools" - any question containing "3tg" and a usage / overview verb The returned `content` is a Markdown guide covering: what 3TG does, first-time setup (clientId + `.3tg/settings.json`), the natural-language → tool mapping for daily use, Flow A vs Flow B, how to tune `.3tg/settings.json`, and how to diagnose enrichment / quota failures. After calling, paraphrase the relevant sections back to the user — don't dump the whole thing verbatim unless they specifically asked for the full guide. For "what is 3tg?", the "What it does" paragraph suffices. For "how do I get started?", combine "First-time setup" + "Daily use". This tool does NOT consume quota and does NOT require a clientId. There is no reason NOT to call it for 3TG questions.

Generate a Jest manual mock file for a specific exported function. 3TG writes the mock to `<srcDir>/__mocks__/<basename>.<ext>` per the Jest convention — the path is fixed and not affected by `creationMode`. Use this when isolating a downstream test from a known dependency. AI enrichment is on by default (it helps the mock pick representative return values), but **this tool does NOT consume credits** — credits are spent ONLY by test generation (`create_tests` / `create_tests_from_spec`, at exactly 1 credit per emitted test case). Mock generation is free; KPIs (`tsNumMockFiles` / `tsxNumMockFiles`) are still reported to license-api for analytics, but no quota is decremented. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's `files` array. After this tool returns, you MUST iterate over `files` and write each entry's `content` verbatim to its `path` using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the `.3tg/` mirror convention where applicable (e.g. specs land under `.3tg/<source-path>.3tg.md`; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.