Add end-to-end evaluation tests and project documentation

.github/workflows/ci.yml

@@ -3,8 +3,10 @@ name: CI
 on:
   push:
     branches: [main]
+  # Run on every PR, including stacked PRs that target feature branches (not
+  # only PRs into main), so format/lint/typecheck/test/build issues are caught
+  # early while the repo grows.
   pull_request:
-    branches: [main]
 
 permissions:
   contents: read

.gitignore

@@ -3,3 +3,6 @@ dist/
 .env
 .cache/
 npm-debug.log*
+
+# Temp output from integration tests that write generated projects to disk
+.tmp-*/

CONTRIBUTING.md

@@ -1,61 +1,96 @@
-# Contributing to Rocket.Chat MCP Server Generator
+# Contributing
 
-Thanks for helping improve the Rocket.Chat MCP Server Generator. This project is a TypeScript MCP server that discovers Rocket.Chat REST APIs, exposes schema inspection tools, and generates focused workflow-driven MCP servers.
+Thanks for helping improve the Rocket.Chat MCP Server Generator. This guide covers everything you need to set up, develop, test, and submit changes.
+
+---
 
 ## Prerequisites
 
-- Node.js 22 or newer
-- npm
-- Git
+- **Node.js 22 or newer**
+- **npm**
+- **Git**
+- **gemini-cli** — optional, only if you want to test the repo as a Gemini extension
 
-## Getting Started
+## Setup
 
-Clone the repository and install dependencies:
+Clone and install:
 
 ```bash
 git clone https://github.com/RocketChat/MCPServerGenerator_GSoC2026.git
 cd MCPServerGenerator_GSoC2026
 npm install
 ```
 
-Run the local validation checks:
+Verify your environment:
 
 ```bash
 npm run typecheck
-npm run test:unit
+npm test
 npm run build
 ```
 
+## Everyday Commands
+
+| Command                                   | What it does                                                   |
+| ----------------------------------------- | -------------------------------------------------------------- |
+| `npm run dev`                             | Run the MCP server from source (via `tsx`) for local iteration |
+| `npm start`                               | Run the compiled server from `dist/`                           |
+| `npm run build`                           | Compile TypeScript to `dist/`                                  |
+| `npm run typecheck`                       | Type-check without emitting files                              |
+| `npm test`                                | Run the full unit/integration test suite                       |
+| `npm run lint` / `npm run lint:fix`       | Lint (and auto-fix) with ESLint                                |
+| `npm run format` / `npm run format:check` | Format (and check) with Prettier                               |
+| `npm run check`                           | Everything above, gate-style — run this before pushing         |
+
 ## Development Workflow
 
-Use the development entry point while iterating locally:
+1. Create a branch with a descriptive name, e.g. `fix/schema-output` or `docs/dsl-reference`.
+2. Make focused changes. Keep refactors out of feature/bug-fix PRs unless required for the fix.
+3. Add or update tests for new behavior.
+4. Run `npm run check` and make sure it passes.
+5. Open a pull request (see the checklist below).
 
-```bash
-npm run dev
-```
+## Coding Conventions
 
-Use the compiled entry point after a build:
+- **TypeScript strict mode**, ESM syntax.
+- Local imports must include the runtime `.js` extension: `import { createMcpServer } from "./server.js";`.
+- **Lint & format are enforced.** ESLint + Prettier run in `npm run check`.
+- **Logging goes to stderr.** Never write to stdout in the MCP server — stdout is the JSON-RPC channel. Use `console.error`.
+- **Prefer narrow interfaces.** Tool handlers should depend on small contracts instead of concrete classes — this keeps handlers testable.
+- Keep tool handlers focused on MCP response shaping; put parsing and workflow logic in the parser/composer/workflow modules.
+- Use lowercase, hyphenated filenames for multi-word modules (e.g. `get-endpoint-schemas.ts`).
 
-```bash
-npm start
-```
+## Where Things Live
 
-Before opening a pull request, run the full project check when your environment can support all tests:
+The source is organized by responsibility under `src/`:
 
-```bash
-npm run check
-```
+| Directory        | Responsibility                                          |
+| ---------------- | ------------------------------------------------------- |
+| `src/tools/`     | The three MCP tool handlers                             |
+| `src/dsl/`       | DSL parser (scanner + recursive descent parser)         |
+| `src/composer/`  | Workflow validation, normalization, inference, ordering |
+| `src/generator/` | Code generation pipeline                                |
+| `src/parser/`    | OpenAPI fetch, cache, endpoint extraction               |
+| `src/workflow/`  | Runtime engine (executor, templates, sandbox, security) |
+| `src/utils/`     | operationId resolver                                    |
 
-## Code Quality
+For a full explanation of the architecture, read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
-This repository uses TypeScript, ESLint, Prettier, and Node's built-in test runner. Keep changes focused and run the relevant checks before submitting work:
+## Testing Conventions
 
-```bash
-npm run format:check
-npm run lint
-npm run typecheck
-npm run test:unit
-npm run build
-```
+Tests use Node's built-in `node:test` with `node:assert/strict`. Tests live under `src/tests/`, grouped by area. Place new tests in the folder matching the module you're changing.
+
+When changing **parser** behavior, cover: exact operationId matches, fuzzy-corrected ids, unmatched ids, request-body extraction, and response schema output.
+
+When changing the **composer** or **workflow engine**, cover the normalization/validation rule you touched and at least one end-to-end case.
+
+See [`docs/TESTING.md`](docs/TESTING.md) for the full test suite map.
+
+## Pull Request Checklist
+
+Before requesting review:
 
-Use `npm run format` only when you intentionally want Prettier to rewrite files.
+- [ ] `npm run check` passes (format, lint, types, tests, build)
+- [ ] New behavior has focused tests
+- [ ] Public MCP tool behavior is documented or covered by a smoke test
+- [ ] Relevant docs updated if behavior or structure changed

GEMINI.md

@@ -380,6 +380,7 @@ STEP post_report : api_call
 ```
 
 **Do NOT** put complex logic directly in MAP:
+
 ```
 # ❌ WRONG — MAP does not support heredoc or complex expressions
 MAP text = <<<

README.md

@@ -1,16 +1,68 @@
-# Rocket.Chat MCP Server Generator
+<h1 align="center">Rocket.Chat MCP Server Generator</h1>
 
-A tool that generates minimal MCP servers for Rocket.Chat — covering only the subset of APIs a project actually needs, instead of bundling every endpoint. This cuts down the context bloat that makes MCP expensive in agentic workflows, and can bring Rocket.Chat code generation projects within the free tier of most LLM platform providers.
+<p align="center">
+  A <a href="https://github.com/google-gemini/gemini-cli">gemini-cli</a> extension that generates <strong>minimal</strong>, <strong>workflow-driven</strong> MCP servers — solving context bloat by exposing only the workflows a project actually needs.
+</p>
 
-## Current Status
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js >= 22"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.8-blue.svg" alt="TypeScript"></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.27-purple.svg" alt="MCP SDK"></a>
+  <a href="https://rocket.chat/"><img src="https://img.shields.io/badge/Rocket.Chat-558%20endpoints-red.svg" alt="558 Endpoints"></a>
+</p>
 
-Implemented:
+---
 
-- Parses Rocket.Chat OpenAPI specs by domain
-- Lists compact endpoint capability guides
-- Returns request and response schemas for selected operationIds
-- Uses memory and disk cache for specs
-- Includes unit and integration tests
+## The Problem
+
+A major pain point when adopting MCP is **context bloat**. Most MCP servers ship support for a large surface of service APIs, so anyone adopting them spends most of their token budget on static tool definitions for calls they will never make. In agentic code-generation workflows this is worse — every agent burns tokens in loops carrying tools the project will never use.
+
+## The Solution
+
+This generator lets you create a **minimal** MCP server that covers only the subset of APIs your project actually needs. Describe what you want in plain English; the generator finds the relevant REST APIs, composes multi-step workflow tools that chain those API calls with AI reasoning, and outputs a complete, runnable MCP server project.
+
+The output is **not** a thin REST wrapper. Each generated tool is a **workflow** that chains multiple API calls, LLM reasoning, user confirmation, data transforms, and conditional logic into one higher-level operation — invoked from any MCP-compatible client such as Gemini CLI, Claude Desktop, Cursor, or VS Code Copilot.
+
+## How It Works
+
+It is itself an MCP server that exposes three tools. An AI client calls them in sequence:
+
+| Tool                       | Purpose                                                                    |
+| -------------------------- | -------------------------------------------------------------------------- |
+| **`get_capability_guide`** | Discovers and lists the available REST API endpoints                       |
+| **`get_endpoint_schemas`** | Returns exact request/response schemas for the chosen endpoints            |
+| **`generate`**             | Validates the described workflows and writes a complete MCP server project |
+
+```
+Describe intent -> get_capability_guide -> get_endpoint_schemas -> generate -> ready to deploy
+```
+
+You describe the goal in natural language; the AI handles endpoint selection, workflow composition, and code generation autonomously.
+
+## Key Capabilities
+
+- **Plain-English to working server** — go from an idea to a complete, tested MCP server project without writing the integration by hand.
+- **Workflow tools, not raw endpoints** — each tool composes API calls, AI reasoning (sampling), human-in-the-loop confirmation (elicitation), data transforms, and conditional branching.
+- **Minimal by design** — only the workflows you ask for are generated, keeping the token footprint small.
+- **Automatic API discovery** — fetches official OpenAPI specs at runtime (558 Rocket.Chat endpoints across 12 domains), so new endpoints are available without manual definitions.
+- **Complete project output** — every generated server includes source, a runtime workflow engine, tests, configuration, and a README.
+- **Two ways to run** — as a Gemini CLI extension (AI-driven), or as a standalone MCP server for deterministic generation.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) v22 or newer
+- [gemini-cli](https://github.com/google-gemini/gemini-cli) installed and configured (for the AI-driven flow)
+
+## Quick Start
+
+Install as a Gemini CLI extension, then describe what you need:
+
+```
+gemini> I need an MCP server that can send messages and manage channels
+```
+
+Gemini discovers the right endpoints, composes the workflows, and generates a complete project — ready to install and run.
 
 ## Building & Testing
 
@@ -19,3 +71,16 @@ npm install
 npm test
 npm run build
 ```
+
+## Documentation
+
+- **[Architecture & High-Level Design](docs/ARCHITECTURE.md)** — how the system fits together
+- **[DSL Reference](docs/DSL_REFERENCE.md)** — the complete DSL language spec
+- **[Generated Project Anatomy](docs/GENERATED_PROJECT.md)** — what the output looks like
+- **[Security Model](docs/SECURITY.md)** — sandbox, allowlist, and threat model
+- **[Testing Guide](docs/TESTING.md)** — test suite map and conventions
+- **[Contributing](CONTRIBUTING.md)** — setup, workflow, and contribution guide
+
+## License
+
+[MIT](LICENSE)