{
  "markdown": "# Minimal MCP Server Generator for Rocket.Chat\n\n> **GSoC 2026 · Rocket.Chat · Mentor(s): Hardik Bhatia, Dhairyashil Shinde**\n\n## The Problem You Already Know\n\nIf you've built an MCP server, you've hit this wall:\n\nYou register tools for an LLM agent. Each tool carries its name, description, and full JSON Schema parameters — all serialized into the context window on every single prompt. For a platform like Rocket.Chat with **547 REST API endpoints** across 12 OpenAPI specs, that's **~115,200 tokens** injected before the model even starts reasoning.\n\nIn agentic loops, this cost compounds: `O(N × T)` — where `N` is iterations and `T` is token waste per iteration. Five agentic runs on Gemini 2.0 Flash's free tier? Budget gone. The model hasn't even written useful code yet.\n\nBut the waste isn't just financial. It's structural:\n\n| What breaks | Why |\n|---|---|\n| **Token Burning** | Agents in loops pay ~115K tokens **per iteration** on static tool definitions. 100 iterations/day = 11.5M tokens burned — most of it on APIs the project will never use. On free-tier plans, budget exhausts in ~5 runs |\n| **Tool Confusion & Hallucination** | 547 tools with near-identical prefixes (`channels.list` vs `channels.list.joined` vs `channels.online`) cause the model to invoke the wrong endpoint. This triggers cascade failures: wrong tool → bad response → retry with another wrong tool → each retry re-pays the full 115K context cost |\n| **Reasoning Degradation** | Static JSON Schema bloat consumes the context window, leaving less room for Chain-of-Thought reasoning, degrading output quality, and increasing response latency |\n| **Cost scalability** | Every agent iteration re-pays the full 115K token tax, making MCP adoption economically unviable for open-source projects on free-tier plans |\n\nThis is the \"context bloat\" problem. Every current MCP server has it. Most teams work around it. We fix it at the root.\n\n---\n\n## What This Project Does\n\n`rc-mcp` generates **standalone, minimal MCP servers** containing only the 2–12 Rocket.Chat API endpoints your agent actually needs. The generated server is a complete, independent Node.js project — not a filtered view of a monolith.\n\n```\nBefore:  LLM ──→ Full MCP Server (547 tools, ~115K tokens) ──→ tool confusion, token waste\nAfter:   LLM ──→ Minimal MCP Server (2-12 tools, ~795 tokens) ──→ correct tool use, 99.7% savings\n```\n\nThe generation pipeline uses **zero LLM calls**. Same `operationIds` in → same server out. Every time, deterministically.\n\n### The Result\n\n| Metric | Full Server | Generated Minimal Server | Reduction |\n|---|:---:|:---:|:---:|\n| Endpoints | 547 | 2 | **99.6%** |\n| Schema payload | 2.2 MB | 3.1 KB | **99.9%** |\n| JSON Schema components | 138 | 3 | **97.8%** |\n| Average Token footprint | ~115,201 | ~795 | **99.7%** |\n\nThese numbers are not estimates. They're computed by the built-in `rc_analyze_minimality` tool and are reproducible on every run.\n\n---\n\n<div align=\"center\">\n  <a href=\"https://youtu.be/kqjsCxgBl5A\">\n    <img src=\"https://img.youtube.com/vi/kqjsCxgBl5A/maxresdefault.jpg\" alt=\"Minimal MCP Server Generator — Full Demo\" width=\"80%\">\n  </a>\n  <p><em>▶ Watch the end-to-end demo: natural language → generated server → validated & proven minimal</em></p>\n</div>\n\n---\n\n## Architecture\n\n**Validation: 13/15 GSoC requirements met · 4/5 mentor criteria · 13/13 workflows are platform-level operations**\n\nThe system has two layers. AI handles discovery. Code generation is entirely deterministic.\n\n```mermaid\nflowchart TB\n    subgraph USER[\"User Intent\"]\n        I[\"'Build me a server for sending messages'\"]\n    end\n\n    subgraph AGENT[\"Gemini CLI Agent\"]\n        O[\"Orchestrator · src/extension/server.ts\"]\n    end\n\n    subgraph L1[\"Layer 1: AI Discovery (4 tools)\"]\n        S[\"rc_suggest_endpoints · TF-IDF + SynonymMap\"]\n        SE[\"rc_search_endpoints · text search + synonyms\"]\n        D[\"rc_discover_endpoints · tag-based browsing\"]\n        W[\"rc_list_workflows · 13 compositions\"]\n    end\n\n    subgraph L2[\"Layer 2: Deterministic Generation (1 tool)\"]\n        G[\"rc_generate_server\"]\n        subgraph PIPE[\"Generation Pipeline (zero LLM)\"]\n            P1[\"1. Workflow Registry · Resolve workflows → operationIds\"]\n            P2[\"2. Schema Extractor · Lazy domain load → $ref pruning\"]\n            P3[\"3. Tool Generator + WorkflowComposer · Zod schemas + handlers\"]\n            P4[\"4. Server Scaffolder · Handlebars → Node.js project + Tests\"]\n        end\n        subgraph POST[\"Auto Post-Generation\"]\n            P5[\"npm install + build\"]\n            P6[\"~/.gemini/settings.json registration\"]\n            P7[\"Structural validation + tsc --noEmit\"]\n            P8[\"Minimality Analyzer · Token reduction proof\"]\n        end\n    end\n    \n    subgraph EVAL[\"Offline Evaluation / CI\"]\n        B1[\"run-benchmarks.ts\"]\n        B2[\"BENCHMARKS.md (99.5% average reduction proof)\"]\n    end\n    \n    subgraph OUT[\"Output\"]\n        M[\"Production MCP Server\"]\n    end\n    \n    subgraph L3[\"Layer 3: Agent Diagnostics (2 tools)\"]\n        V[\"rc_validate_server\"]\n        A[\"rc_analyze_minimality\"]\n    end\n    \n    %% Flow logic\n    I --> O --> S & SE & D & W\n    S & SE & D & W -- \"Selected IDs / Workflows\" --> G\n    \n    G --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8 --> M\n    M -.-> V\n    M -.-> A\n    \n    %% Benchmarks linking to the specific classes they test\n    P1 -. \"Tests all workflows\" .-> B1\n    P2 -. \"Extracts schemas\" .-> B1\n    P8 -. \"Calculates tokens\" .-> B1\n    B1 --> B2\n```\n\n**Why two layers?** AI is useful for figuring out *which* endpoints to include. It has no place in the code generation itself. Mixing LLM inference into scaffolding introduces non-determinism, token cost, and hallucination risk — exactly the problems we're solving.\n\n### Abstraction Level: Platform Operations, Not API Wrappers\n\nThe GSoC spec requires: *\"The tool must generate MCP servers and NOT just RC API wrappers. MCP servers typically address much higher (platform) level operations.\"*\n\nAll 13 workflow compositions pass this test — each chains 2-4 API calls into a single user-intent operation:\n\n| Workflow | Steps | What it hides | Abstraction level |\n|---|:---:|---|:---:|\n| `send_message_to_channel` | 2 | Channel name → ID resolution | ✅ Platform |\n| `create_project_channel` | 3 | Create + set description + set topic | ✅ Platform |\n| `invite_users_to_channel` | 2 | Resolve + invite with public/private fallback | ✅ Platform |\n| `create_discussion_in_channel` | 2 | Channel resolution + discussion creation | ✅ Platform |\n| `send_and_pin_message` | 2 | Post + pin in single operation | ✅ Platform |\n| `send_dm_to_user` | 2 | Open DM conversation + send | ✅ Platform |\n| `set_status_and_notify` | 3 | Set status + resolve channel + post update | ✅ Platform |\n| `archive_channel` | 2 | Resolve + archive with public/private fallback | ✅ Platform |\n| `setup_project_workspace` | 4 | Create + describe + topic + welcome message | ✅ Platform |\n| `react_to_last_message` | 2 | Fetch history + react to latest | ✅ Platform |\n| `onboard_user` | 4 | Lookup user + resolve room + invite + welcome | ✅ Platform |\n| `setup_webhook_integration` | 2 | Resolve room + create incoming webhook | ✅ Platform |\n| `export_channel_history` | 2 | Resolve room + fetch messages | ✅ Platform |\n\n**Abstraction score: 13/13** — every workflow represents \"what I want to do\", not \"what API to call\".\n\n### Layer 1: AI Discovery — 4 Tools\n\nThe developer describes what they want in plain English. The Gemini CLI agent uses four discovery tools to identify the right `operationIds` and `workflows`:\n\n| Tool | What it does | How it works internally |\n|---|---|---|\n| `rc_suggest_endpoints` | Maps vague intent → multiple API clusters in one call | V4 `SuggestEngine` (`suggest-engine.ts`, 568 lines): offline weighted keyword scoring (TF-IDF), 59-entry synonym expansion via `synonym-map.ts`, intelligent clustering to ensure a diverse set of tools (set-cover algorithm), and guaranteed domain coverage. Accepts `ProviderConfig` for platform-agnostic operation. |\n| `rc_search_endpoints` | Keyword search across all 547 endpoints | Same synonym expansion + TF-IDF scoring engine, returns flat ranked results instead of clusters |\n| `rc_discover_endpoints` | Browsable tag summaries → expand specific tags on demand | `SchemaExtractor.getEndpointsByTag()` — groups by `Domain → Tag → EndpointSchema[]`. First call returns summaries (~100 lines); expansion reveals individual endpoints. Prevents context blowout during exploration |\n| `rc_list_workflows` | List 13 predefined workflow compositions | `WorkflowRegistry.getWorkflows()` — returns composed tools that combine multiple RC API endpoints into single, higher-level operations (e.g. `send_message_to_channel`). |\n\n### Layer 2: Deterministic Pipeline — 3 Tools\n\nOnce the agent has selected `operationIds` and/or `workflows`, the pipeline executes with zero LLM involvement:\n\n**`rc_generate_server`** orchestrates the Core Engine components, followed by automated post-generation steps:\n\n| Component | File | What it does |\n|---|---|---|\n| **Workflow Registry** | `workflow-registry.ts` (694 lines) | Resolves requested workflow names into exact API operation paths (`WorkflowDefinition`s) prior to schema extraction. Contains 13 predefined workflow compositions. |\n| **Schema Extractor** | `schema-extractor.ts` (495 lines) | Fetches and fully dereferences the 12 Rocket.Chat OpenAPI YAML specs using `@apidevtools/swagger-parser`. Supports **lazy domain loading** via `inferDomainsFromIds()` — scans cached JSON strings to determine which 2-3 domains out of 12 need loading, bypassing unnecessary network overhead. Resolves all nested `$ref` chains. Handles `oneOf`/`anyOf` by merging variants into flat structures. |\n| **Tool Generator** | `tool-generator.ts` (381 lines) & `workflow-composer.ts` (268 lines) | Transforms `EndpointSchema[]` → `GeneratedTool[]`. Filters out auth headers so generated tools use `.env`-based pre-authentication. Uses its internal `WorkflowComposer` sub-engine to generate composite tools via AST mapping, chaining multiple endpoints into single platform operations. Both `ToolGenerator` and `WorkflowComposer` use unified `MAX_DESC_LENGTH = 200` (base truncation at 140 chars). |\n| **Server Scaffolder** | `server-scaffolder.ts` (754 lines) | Assembles a complete Node.js project using 11 Handlebars inline templates. Output: `src/server.ts`, `src/tools/*.ts`, `src/rc-client.ts`, `tests/*.test.ts`, `package.json`, `tsconfig.json`, `.env.example`, `README.md`, `GEMINI.md`, `gemini-extension.json`. |\n\n**Automated post-generation** (all performed by `rc_generate_server` in a single call):\n\n| Step | What it does |\n|---|---|\n| **`.env` creation** | Writes a real `.env` with provided `rcUrl`, `rcAuthToken`, `rcUserId` so the server is pre-authenticated on first run |\n| **`npm install` + `npm run build`** | Installs dependencies and compiles TypeScript (skippable via `installDeps: false`) |\n| **Gemini CLI registration** | Auto-updates `~/.gemini/settings.json` with the new server's MCP entry, so tools are immediately available after restarting gemini (skippable via `registerWithGemini: false`) |\n| **Inline validation** | Checks all required files exist + runs `tsc --noEmit` for type safety |\n| **Minimality analysis** | Computes 4-dimension pruning report inline — no separate tool call needed |\n\n**`rc_validate_server`** audits the generated output across 4 categories:\n\n| Check | What passes |\n|---|---|\n| Structure | `package.json`, `tsconfig.json`, `src/server.ts`, `src/rc-client.ts`, `.env.example` exist |\n| MCP compliance | `@modelcontextprotocol/sdk` and `zod` in dependencies |\n| Tool coverage | Every `src/tools/*.ts` contains `z.object()`; every tool has a matching `tests/*.test.ts` |\n| Deep type safety | `npx tsc --noEmit` inside the generated project — zero TypeScript compilation errors |\n\n**`rc_analyze_minimality`** computes a 4-dimension pruning report: endpoint count reduction, schema payload reduction, component count reduction, and estimated token savings. Uses `$ref` resolution depth tracking (recursive to 15 levels, `minimality-analyzer.ts:L545`) and a 4 chars/token estimation heuristic (`minimality-analyzer.ts:L490`).\n\n---\n\n## The V4 Suggest Engine — How Intent Maps to Endpoints\n\nWhen a developer says *\"build a customer support bot\"*, the engine needs to find the right APIs across messaging, omnichannel, and user management — without any LLM call.\n\nThe `SuggestEngine` class (`src/core/suggest-engine.ts`, 568 lines) powers the `rc_suggest_endpoints` tool. It accepts an optional `ProviderConfig` for platform-agnostic operation (defaults to `RocketChatProvider`). It operates entirely offline, generating highly specialized clusters that are passed directly back to the native Gemini CLI agent to orchestrate:\n\n### Phase 1: Semantic Scoring & Clustering (The Engine)\n\n**Step 1: Tokenization & Synonym Expansion**\n```\nInput:     \"create project channel, invite members, send task updates\"\nTokenized: [\"creat\", \"project\", \"channel\", \"invit\", \"member\", \"send\", \"task\", \"updat\"]\nExpanded:  [\"creat\", \"project\", \"channel\", \"invit\", \"member\", ..., \"add\", \"join\", \"post\", \"chat\", ...]\n```\n\nUses a custom minimal Porter stemmer + 43-word stop set. The synonym map (`synonym-map.ts`, 59 entries) bridges user vocabulary to API vocabulary: `\"invite\"` → `[\"invite\", \"add\", \"join\", \"member\"]`, `\"star\"` → `[\"star\", \"starmessage\", \"starred\", \"bookmark\", \"favorite\"]`.\n\n**Step 2: TF-IDF Scoring with Field Weights**\n\nEvery token is scored against all 547 endpoints. The field the token appears in determines its weight:\n\n| Field | Weight | Why |\n|---|:---:|---|\n| `operationId` | **10×** | Most precise API identifier |\n| `path` | **5×** | Structured endpoint name |\n| `tags` | **3×** | Semantic domain grouping |\n| `summary` | **2×** | Concise OpenAPI description |\n| `description` | **0.1×** | Verbose boilerplate — nearly ignored to prevent false matches |\n\n```\nscore = Σ [ IDF(token) × directWeight × fieldWeight ]\n\n  IDF(token) = log(N / df(token))        — N = 547 endpoints, df = document frequency\n  directWeight = 3 if original intent token, 1 if synonym-only\n  fieldWeight = max weight across all fields containing the token\n```\n\n**Step 3: Cluster Grouping**\n\nEndpoints are grouped by `domain::tag`. Within each cluster:\n- Endpoints scoring <50% of the cluster's top scorer are dropped (noise filtering)\n- Maximum 5 endpoints per cluster\n- Only `fieldWeight ≥ 2` matches count toward coverage (prevents description-text false positives)\n\n**Step 4: Greedy Set-Cover Selection**\n\n```\nwhile remaining_clusters > 0 and selected < 5:\n    for each candidate:\n        new_coverage = uncovered intent tokens this cluster would cover\n        penalty = 0.5 if this domain already selected, else 1.0\n        score = new_coverage × penalty\n    select highest-scoring cluster\n    break if full coverage achieved\n```\n\n**Step 5: Domain Coverage Guarantee**\n\nIf the intent explicitly mentions a domain (detected via `DOMAIN_HINTS`, 65 keyword→domain mappings), the engine force-adds that domain's best cluster — even if the greedy algorithm didn't select it.\n\n**Step 6: Confidence**\n\n```\ncoverage = |covered_original_tokens| / |intent_tokens|\nconfidence = coverage ≥ 0.5 → \"high\" | ≥ 0.25 → \"medium\" | else → \"low\"\n```\n\n### Phase 2: Native Agent Orchestration (The Brain)\n\nOnce the `SuggestEngine` computes the optimal endpoint clusters, the **built-in models inside Gemini CLI** act as the \"Brain.\" There is no need for an external `GEMINI_API_KEY` or custom outbound API calls. The native Gemini agent inspects the TF-IDF results, communicates the options to the user, and autonomously invokes the `rc_generate_server` pipeline.\n\n### Genericity Architecture\n\nThe GSoC spec encourages: *\"Solve this problem more generically. Ideally, the tool can benefit all similar upstream projects/platforms.\"*\n\n**What is generic (works for any OpenAPI spec):**\n\n| Component | Why it's provider-agnostic |\n|---|---|\n| `SchemaExtractor` | Accepts any `ProviderConfig`, uses `provider.specSource.baseUrl` for fetching, `provider.authHeaderKeys` for filtering |\n| `ToolGenerator` | Uses `ProviderConfig.authHeaderKeys` — no RC-specific logic |\n| `WorkflowComposer` | Uses `parameterMappings` from definitions — never hardcodes field names |\n| `ProviderConfig` interface | 10 fields, all provider-agnostic (name, specSource, domainNames, authScheme, authHeaderKeys, apiPrefix) |\n\n**What is RC-specific (pluggable data layer):**\n\n| Component | Why it's RC-only |\n|---|---|\n| `synonym-map.ts` | 59 entries mapping RC vocabulary (`\"invite\"` → `[\"invite\", \"add\", \"join\", \"member\"]`) |\n| `DOMAIN_HINTS` | 65 keyword→domain mappings specific to RC API structure |\n| `workflow-registry.ts` | 13 workflows wired to RC operationIds |\n\n**Verdict:** Architecturally generic — core engine interfaces are provider-agnostic. A second provider (Slack, Mattermost) can be added by implementing `ProviderConfig` and supplying a workflow registry, without modifying core engine code.\n\n---\n\n## How Context Reduction Actually Works\n\nSeven specific techniques, each targeting a different source of token waste:\n\n### 1. Surgical `$ref` Pruning\n`SchemaExtractor` uses `@apidevtools/swagger-parser` to fully dereference all `$ref` chains. Lazy domain loading via `inferDomainsFromIds()` scans cached JSON strings to determine which 2-3 domains (out of 12) actually need loading. The engine prunes 2.2 MB → 3.1 KB.\n\n### 2. Description Compression (≤200 chars)\n`ToolGenerator` enforces `MAX_DESC_LENGTH = 200`, stripping OpenAPI boilerplate:\n```ts\ndesc.replace(/\\s*\\(requires authentication\\)/gi, \"\")\n    .replace(/\\s*\\(admin only\\)/gi, \"\")\n    .replace(/\\s*Permission required:.*$/gi, \"\")\n```\n\n### 3. Startup Auth from `.env`\nGenerated servers are pre-authenticated via `.env` credentials baked in during generation. The `rc-client.ts` calls `rcClient.setAuth(envAuthToken, envUserId)` at startup using environment variables. Individual tool handlers do **not** receive `authToken` or `userId` as parameters — `ToolGenerator` filters out auth headers from generated Zod schemas entirely. This eliminates the login tool from the tool count while keeping the context window clean.\n\nCollision-safe: if a platform ever requires `authToken` or `userId` as API-level fields, the generator's `ProviderConfig.authHeaderKeys` configuration controls which header names are filtered.\n\n### 4. Progressive Disclosure\n`rc_discover_endpoints` returns tag summaries first (~100 lines), not the full endpoint list (~10,000 lines). The agent expands only relevant tags via `expand: [\"tagName\"]`.\n\n### 5. Multi-Cluster Semantic Mapping\nOne call to `rc_suggest_endpoints` returns cross-domain clusters covering all parts of the intent. No iterative prompt engineering needed.\n\n### 6. 2-Tier Caching\n```\nTier 1: Disk (.cache/ — 24h TTL, stored as dereferenced JSON)\n  ↓ miss\nTier 2: GitHub raw fetch (SwaggerParser.dereference(url))\n```\nAfter first run, all operations use the disk cache. Generation completes in milliseconds.\n\n### 7. Zero-LLM Pipeline\n`SchemaExtractor` → `ToolGenerator` → `ServerScaffolder` uses zero API calls. Deterministic, free, and fast.\n\n### Architectural Design Decisions\n\n| Decision | Rationale |\n|---|---|\n| **`.env`-based startup auth** (not per-request injection) | Eliminates `authToken`/`userId` from every tool's Zod schema, saving ~2 params × N tools of context. `ToolGenerator` filters auth headers using `ProviderConfig.authHeaderKeys` |\n| **TF-IDF + synonyms** (not LLM-based discovery) | Zero token cost for discovery. Same intent → same results, every time |\n| **Greedy set-cover with domain penalty** | Ensures cross-domain diversity (e.g., user-management isn't blocked by rooms winning) |\n| **`ProviderConfig` interface** | Structural genericity: synonym maps and workflow registries are pluggable data, not hardcoded logic |\n| **Fallback operationIds in workflows** | 4/13 workflows handle public/private channel ambiguity via `fallbackOperationId` (try `channels.*`, fall back to `groups.*`) |\n| **Token estimation heuristic (4 chars/token)** | Approximate but consistent for relative comparisons. Clearly marked as `~` in all output |\n\n---\n\n## Quick Start\n\n### Install & Link\n\n```bash\ngit clone https://github.com/thekishandev/MCP-Server-Generator.git\ncd MCP-Server-Generator\nnpm install && npm run build\n\n# Register as a Gemini CLI extension\ngemini extensions link .\n```\n\n### Generate a Server (Agentic Workflow)\n\n```bash\ngemini\n```\n\n> *\"Generate MCP server for team collaboration that sends direct messages, creates discussion threads, reacts to messages with emoji and pins important announcements.\"*\n\nThe Gemini agent will:\n1. Call `rc_suggest_endpoints` → receive multi-cluster suggestions\n2. Confirm the endpoint list with you\n3. Call `rc_generate_server` → write files, install deps, build, register with Gemini CLI, validate, and run minimality analysis — **all in one call**\n4. Output a ready-to-use server — just restart `gemini` and the new tools are available\n\n### Generate a Server (Direct CLI — No LLM)\n\n```bash\nrc-mcp suggest \"send messages and manage channels\" --generate -o ./my-server\nrc-mcp validate ./my-server --deep\nrc-mcp analyze --endpoints post-api-v1-chat-sendMessage,post-api-v1-channels-create\n```\n\n---\n\n## MCP Tools Reference\n\n7 tools registered via `@modelcontextprotocol/sdk` using `StdioServerTransport`:\n\n| Tool | Purpose | Parameters |\n|---|---|---|\n| `rc_suggest_endpoints` | Intent → multi-cluster API suggestions | `intent: string` |\n| `rc_search_endpoints` | Keyword search across 547 endpoints | `query: string`, `domains?: Domain[]`, `limit?: number` |\n| `rc_discover_endpoints` | Tag summaries → expandable endpoint lists | `domains: Domain[]`, `expand?: string[]` |\n| `rc_list_workflows`      | List 13 predefined composite workflows | `{}` |\n| `rc_generate_server` | Scaffold, install, build, register, validate — all-in-one | `operationIds?: string[]`, `workflows?: string[]`, `outputDir: string`, `serverName?`, `rcUrl?`, `rcAuthToken?`, `rcUserId?`, `installDeps?`, `registerWithGemini?` |\n| `rc_analyze_minimality` | 4-dimension pruning proof | `operationIds: string[]` |\n| `rc_validate_server` | Structure + MCP + Zod + `tsc` validation | `serverDir: string`, `deep?: boolean` |\n\n**`rc_generate_server` auto-performs** (saves 2+ round-trip tool calls):\n- ✅ Writes `.env` with provided credentials (pre-authenticated on first run)\n- ✅ `npm install` + `npm run build`\n- ✅ Registers in `~/.gemini/settings.json` (restart gemini to use new tools)\n- ✅ Structural validation + `tsc --noEmit` type check\n- ✅ 4-dimension minimality analysis\n\n**12 Supported Domains:** `authentication` · `messaging` · `rooms` · `user-management` · `omnichannel` · `integrations` · `settings` · `statistics` · `notifications` · `content-management` · `marketplace-apps` · `miscellaneous`\n\n---\n\n## Validation & Testing\n\n### 102 Tests (97 Passing, 5 Skipped) · 0 TypeScript Errors\n\n```bash\nnpm test\n```\n\n| Suite | What it validates |\n|---|---|\n| `suggest-engine.test.ts` | TF-IDF scoring accuracy, synonym expansion, cluster grouping, deduplication, search results |\n| `tool-generator.test.ts` | Zod codegen correctness, auth injection, description compression, handler generation |\n| `server-scaffolder.test.ts` | Template rendering, file output structure, `package.json` integrity |\n| `schema-extractor.test.ts` | Domain loading, endpoint indexing, fuzzy matching |\n| `minimality-analyzer.test.ts` | Reduction calculations, `$ref` depth analysis, report formatting |\n| `workflow-composer.test.ts` | Zod schema generation and AST chaining correctness |\n| `workflow-registry.test.ts` | Registry validation and workflow fetching |\n| `workflow-integration.test.ts` | 13 workflow compositions proven correct with handler resolution |\n| `workflow-e2e.test.ts` | End-to-end composite tool generation validation |\n| `extension-server.test.ts` | MCP tool registration, server export verification |\n| `provider-config.test.ts` | Provider configuration tests |\n| 30+ generated tool tests | Dynamic Zod `safeParse` validation, shape introspection, type rejection |\n\n### Generated Test Intelligence\n\nTest files are not `expect(true)` stubs. Each generated test:\n1. Asserts the schema is a `z.ZodObject` instance\n2. Inspects `.shape` to identify required fields\n3. Verifies `safeParse({})` fails when required fields exist\n4. Rejects invalid data types (`string` where `object` expected)\n\n---\n\n## Gemini CLI Extension Integration\n\nBuilt following [Gemini CLI Extension Best Practices](https://geminicli.com/docs/extensions/best-practices/):\n\n| Practice | Implementation |\n|---|---|\n| Environment auth | Credentials are provided via `.env` files to the generated servers, executing as independent process |\n| Contextual docs | Auto-generates `GEMINI.md` documenting available tools, parameters, auth requirements |\n| TypeScript build | Full TypeScript project → `tsc` → `dist/` JavaScript output |\n| Minimal permissions | Only 2-12 tools exposed → agent physically cannot invoke unrelated APIs |\n| Gallery-ready | `gemini-extension.json` at repo root → `gemini extensions install <url>` |\n| Local dev | `gemini extensions link .` for instant iteration |\n| Auto-registration | `rc_generate_server` auto-updates `~/.gemini/settings.json` — no manual config needed |\n\n---\n\n## Project Structure\n\n```\nMCP-Server-Generator/\n├── src/\n│   ├── cli/\n│   │   └── index.ts                    # Commander.js CLI entry point (708 lines)\n│   ├── core/\n│   │   ├── types.ts                    # 17 shared TypeScript types (206 lines)\n│   │   ├── schema-extractor.ts         # OpenAPI parser + lazy domain loading (495 lines)\n│   │   ├── tool-generator.ts           # JSON Schema → Zod codegen (381 lines)\n│   │   ├── server-scaffolder.ts        # 11 Handlebars templates (754 lines)\n│   │   ├── suggest-engine.ts           # V4 TF-IDF engine (568 lines)\n│   │   ├── synonym-map.ts              # 59 synonyms + 65 domain hints (243 lines)\n│   │   ├── minimality-analyzer.ts      # 4-dimension analysis (677 lines)\n│   │   ├── gemini-integration.ts       # Extension manifest generator (270 lines)\n│   │   ├── workflow-registry.ts        # 13 predefined RC workflows (694 lines)\n│   │   ├── workflow-composer.ts        # Composite tool logic (268 lines)\n│   │   ├── provider-config.ts          # Provider specifications (133 lines)\n│   │   └── index.ts                    # Barrel export\n│   └── extension/\n│       └── server.ts                   # Live 7-tool MCP server (665 lines)\n├── tests/                              # 11 test files, 102 tests\n├── .cache/                             # Dereferenced OpenAPI JSON (24h TTL)\n├── gemini-extension.json               # Extension manifest (v0.2.0)\n├── GEMINI.md                           # LLM context instructions\n└── package.json                        # rc-mcp v0.1.0\n```\n\n---\n\n## Technical Stack\n\n| Layer | Technology | Version |\n|---|---|---|\n| Language | TypeScript (strict, ES2022, NodeNext) | ^5.7.0 |\n| Runtime | Node.js | ≥18.0.0 |\n| CLI | Commander.js | ^12.1.0 |\n| OpenAPI Parser | `@apidevtools/swagger-parser` | ^12.1.0 |\n| Templates | Handlebars | ^4.7.8 |\n| Schema Validation | Zod | ^3.25.76 |\n| MCP SDK | `@modelcontextprotocol/sdk` | ^1.27.1 |\n| Testing | Vitest | ^4.0.18 |\n| YAML | yaml | ^2.6.1 |\n| Terminal UX | Chalk + Ora | ^5.3.0 / ^8.1.1 |\n\n**OpenAPI Compatibility:** `SchemaExtractor` uses `@apidevtools/swagger-parser` to ingest and fully dereference any OpenAPI 3.x specification. The `ProviderConfig.specSource.baseUrl` accepts arbitrary spec URLs, making the core engine compatible with any OpenAPI-compliant service. OpenClaw compatibility is structurally supported through the same OpenAPI ingestion path.\n\n---\n\n## License\n\nMIT — A GSoC 2026 project with [Rocket.Chat](https://rocket.chat)\n",
  "bytes": 27844,
  "sha": "fdf3b01160af60bb6afe22aad5ce3df2909d66e28fc9c13092baa6506dd4e209",
  "repo_slug": "thekishandev/mcp-server-generator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_thekishandev_mcp_server_generator_2dbb3dcb/readme"
}