mcp-react-toolkit 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# Contributing to mcp-toolkit
+
+Thanks for your interest. This project is a collection of MCP servers for React + TypeScript development automation. The fastest way to contribute is to implement one of the [planned tools](README.md#roadmap) from the roadmap.
+
+---
+
+## Quick start
+
+```sh
+git clone https://github.com/Nishant-Chaudhary5338/mcp-toolkit.git
+cd mcp-toolkit
+npm install
+npm run build
+npm test
+```
+
+Requires Node.js 20+.
+
+---
+
+## Adding a new MCP tool
+
+Each tool lives in `tools/<tool-name>/` and extends the shared `McpServerBase` class.
+
+### 1. Scaffold the package
+
+```sh
+mkdir -p tools/my-tool/src
+```
+
+**`tools/my-tool/package.json`**
+```json
+{
+  "name": "@mcp-showcase/my-tool",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./build/index.js",
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@mcp-showcase/shared": "*",
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}
+```
+
+**`tools/my-tool/tsconfig.json`**
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./build",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}
+```
+
+### 2. Implement the server
+
+**`tools/my-tool/src/index.ts`**
+```typescript
+#!/usr/bin/env node
+import { McpServerBase } from '@mcp-showcase/shared';
+
+class MyToolServer extends McpServerBase {
+  constructor() {
+    super({ name: 'my-tool', version: '1.0.0' });
+  }
+
+  protected registerTools(): void {
+    this.addTool(
+      'my_action',
+      'Describe what this tool does in one sentence.',
+      {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Absolute path to target directory' },
+        },
+        required: ['path'],
+      },
+      async (args) => {
+        const { path } = args as { path: string };
+        // your logic here
+        return this.success({ result: `Processed ${path}` });
+      }
+    );
+  }
+}
+
+new MyToolServer().run();
+```
+
+### 3. Write tests
+
+**`tools/my-tool/src/index.test.ts`**
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+// Test the tool logic directly — bypass MCP transport entirely
+describe('my-tool', () => {
+  it('returns success shape on valid input', async () => {
+    // Import your handler logic (extract it from the class if needed)
+    const result = { success: true, result: 'Processed /some/path' };
+    expect(result.success).toBe(true);
+    expect(result.result).toContain('/some/path');
+  });
+});
+```
+
+### 4. Add to the workspace
+
+In the root `package.json`, add `"tools/my-tool"` to the `workspaces` array and add the build step to the `build` script.
+
+### 5. Update the roadmap
+
+In `README.md`, change the tool's row from `📋 Planned` to `🚧 In progress`, then to `✅ Done` once merged.
+
+Also update `client/src/data/tools.ts` — set `available: true` for the tool's entry so the UI shows it as real.
+
+---
+
+## Standards
+
+- **TypeScript strict** — no `any`, explicit return types on exports
+- **Error handling** — use `this.error(err)` from `McpServerBase`; never let unhandled exceptions crash the server
+- **Tests** — minimum 3 test cases per tool (happy path, invalid input, edge case)
+- **No comments** that restate the code — comment only non-obvious constraints
+- **One tool per file** for tools with complex logic (see `code-modernizer/src/tools/`)
+
+---
+
+## PR checklist
+
+- [ ] `npm run build` passes with no TypeScript errors
+- [ ] `npm test` passes
+- [ ] README roadmap updated (status changed to ✅ Done)
+- [ ] `client/src/data/tools.ts` entry updated (`available: true`)
+- [ ] Tool tested manually with Claude Desktop or Cline
+
+---
+
+## Reporting bugs
+
+Use [GitHub Issues](https://github.com/Nishant-Chaudhary5338/mcp-toolkit/issues/new?template=bug_report.md). Include the tool name, the input you passed, and the full error output.
+
+## Questions
+
+Open a [Discussion](https://github.com/Nishant-Chaudhary5338/mcp-toolkit/discussions) — not an issue.

package/HOW_IT_WORKS.md

@@ -0,0 +1,270 @@
+# How DevForge Works
+
+> A plain-English explanation of the architecture, the protocol, and why everything runs fast.
+
+---
+
+## The 30-Second Version
+
+When you click "Run" in the UI, this happens:
+
+```
+Your Browser  →  Express Server  →  Node.js subprocess  →  your files on disk
+     ↑                                                              ↓
+  Results  ←────────────────────────────────────────────────────────
+```
+
+No cloud. No AI model. No API keys. Everything executes locally on your machine in ~200–500ms.
+
+---
+
+## What Is MCP?
+
+MCP stands for **Model Context Protocol**. It's a standard created by Anthropic so that AI models (like Claude) can call external tools — read files, run commands, search databases — in a safe, structured way.
+
+Think of it like a job posting system:
+- The **tool** says: "I can do these things, here's what I need as input"
+- The **client** (normally an AI model, here our server) says: "Great, do this specific thing with these arguments"
+- The **tool** does the work and returns a result
+
+The protocol itself is just JSON messages sent back and forth. That's it.
+
+---
+
+## The Full Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Browser (React + Vite, port 5177)                          │
+│                                                             │
+│  [Component Factory]  [Code Modernizer]  [Quality Pipeline] │
+│         ↓                    ↓                   ↓          │
+│         └──────────── POST /api/call ────────────┘          │
+└─────────────────────────────┬───────────────────────────────┘
+                              │  { server, tool, args }
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Express Server (port 3002)  server/src/index.ts            │
+│                                                             │
+│  Receives the request, looks up which tool to run,          │
+│  spawns it as a child process, speaks MCP protocol          │
+│  over stdin/stdout, returns the JSON result                 │
+└─────────────────────────────┬───────────────────────────────┘
+                              │  node tools/<name>/build/index.js
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  MCP Tool (Node.js subprocess)                              │
+│                                                             │
+│  • Reads files from disk                                    │
+│  • Runs regex / AST analysis                                │
+│  • Executes shell commands (tsc, vitest)                    │
+│  • Returns structured JSON                                  │
+│  • Process exits when done                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Why Is It Fast?
+
+Because **nothing leaves your machine**.
+
+A typical AI-powered tool makes an HTTP request to a cloud API, waits for inference (500ms–3s), and returns. DevForge tools don't call any AI. They are just Node.js programs doing:
+
+- `fs.readFileSync()` — read a file
+- `RegExp.exec()` — match patterns
+- `execSync('tsc --noEmit')` — run a command
+
+Your CPU can do millions of regex matches per second. Reading 5 files off an SSD takes under 5ms. That's why the quality pipeline runs 5 checks across a project in under 500ms.
+
+---
+
+## The MCP Wire Protocol
+
+This is what actually goes over stdin/stdout between the server and each tool. It's boring on purpose — just JSON lines.
+
+```
+Server → Tool:  { "jsonrpc": "2.0", "method": "initialize", "id": 1, "params": { ... } }
+Tool → Server:  { "jsonrpc": "2.0", "id": 1, "result": { "capabilities": {} } }
+
+Server → Tool:  { "jsonrpc": "2.0", "method": "initialized" }
+
+Server → Tool:  {
+                  "jsonrpc": "2.0",
+                  "method": "tools/call",
+                  "id": 2,
+                  "params": {
+                    "name": "run_partial_pipeline",
+                    "arguments": { "projectRoot": "/some/path", "stages": ["performance"] }
+                  }
+                }
+
+Tool → Server:  {
+                  "jsonrpc": "2.0",
+                  "id": 2,
+                  "result": {
+                    "content": [{ "type": "text", "text": "{...your result as JSON string...}" }]
+                  }
+                }
+```
+
+The tool process starts, does a handshake, handles one tool call, returns the result, and exits. The server kills it. Next request = new process. Clean, isolated, no shared state.
+
+---
+
+## How Each Tool Works Internally
+
+### Component Factory
+
+**What it does:** Generates production-ready React components from real shadcn/ui templates.
+
+**How:**
+1. Reads the 41 `.tsx` template files from `tools/component-factory/templates/` at runtime
+2. Takes the template source code and transforms it — renames the component, adjusts imports, generates TypeScript prop interfaces
+3. Generates test files (Vitest) and story files (Storybook) as string templates
+4. Writes all files to the output path you specify
+
+**The key insight:** These are real, working component files — not AI-hallucinated code. The template is already correct. The tool just adapts it and wires it together.
+
+```
+button.tsx (template)  →  transform  →  /tmp/mcp-demo-components/Button/
+                                          Button.tsx       ← the component
+                                          Button.test.tsx  ← vitest tests
+                                          Button.stories.tsx ← storybook
+                                          Button.types.ts  ← interfaces
+```
+
+---
+
+### Code Modernizer
+
+**What it does:** Converts JavaScript/JSX files to TypeScript automatically.
+
+**How:**
+1. Uses `@typescript-eslint/parser` to parse JS/JSX into an **AST** (Abstract Syntax Tree) — a structured tree representation of the code
+2. Walks the AST to find:
+   - Function declarations → what parameters they take
+   - `PropTypes` definitions → convert to TypeScript interfaces (`PropTypes.string` → `string`)
+   - React hooks → infer state types from initial values
+3. Rewrites the file with proper TypeScript annotations and saves it as `.ts`/`.tsx`
+
+**Why AST instead of regex?**
+Regex sees code as text. An AST sees code as structure. Regex can't tell the difference between a string `"PropTypes.string"` in a comment vs actual PropTypes usage. An AST can.
+
+```
+// Input (JS)                    // Output (TS)
+function UserCard(props) {        interface UserCardProps {
+  const { name, age } = props;      name: string
+  return <div>{name}</div>          age: number
+}                                 }
+UserCard.propTypes = {            function UserCard({ name, age }: UserCardProps) {
+  name: PropTypes.string,           return <div>{name}</div>
+  age: PropTypes.number,          }
+}
+```
+
+---
+
+### Quality Pipeline
+
+**What it does:** Runs 5 automated checks on a project and gives an overall grade (A–F).
+
+**How each stage works:**
+
+| Stage | Mechanism |
+|---|---|
+| **Tests** | Runs `npx vitest --reporter=json --outputFile=/tmp/result.json`, reads the JSON file for pass/fail counts |
+| **Type Safety** | Runs `tsc --noEmit`, counts lines matching `error TS` in the output |
+| **Performance** | Scans import statements for known heavy libraries; scans 50 lines after each `useEffect` for missing cleanup (`removeEventListener`, `clearInterval`) |
+| **Accessibility** | Runs multiline regex across full file content — catches `<img>` without alt, buttons without accessible text, inputs without labels, `onClick` without keyboard handlers |
+| **Design Tokens** | Regex `/\d+px/` in style contexts catches *any* hardcoded pixel value — not a fixed list |
+
+**Grading:**
+
+```
+0 fails, 0 warns  → A
+0 fails, 1 warn   → B
+0 fails, 2 warns  → C
+1 fail            → D
+2+ fails          → F
+```
+
+---
+
+## The Subprocess Model (Why Tools Don't Have Ports)
+
+Most people expect a backend service to bind to a port and stay running. MCP tools don't do that.
+
+Each tool is just a script. The server spawns it fresh per request:
+
+```typescript
+// server/src/mcp-client.ts
+const child = spawn('node', ['tools/quality-pipeline/build/index.js'], {
+  stdio: ['pipe', 'pipe', 'pipe']   // control stdin/stdout/stderr
+})
+
+// Write JSON-RPC messages to stdin
+child.stdin.write(JSON.stringify({ method: 'initialize', ... }) + '\n')
+
+// Read responses from stdout
+child.stdout.on('data', chunk => {
+  const response = JSON.parse(chunk)
+  // ... handle handshake, then send tool call, then resolve promise
+})
+
+// Process auto-exits after responding
+// Server calls child.kill() to be safe
+```
+
+Benefits of this model:
+- **No port conflicts** — tools don't need network ports
+- **Perfect isolation** — one failed request can't corrupt the next
+- **Easy to add tools** — drop a new folder in `tools/`, no server config needed
+- **Cheap to run** — processes live for ~200ms, not forever
+
+---
+
+## Workspace Structure
+
+```
+mcp-showcase/
+├── tools/
+│   ├── shared/           ← McpServerBase class all tools extend
+│   ├── component-factory/
+│   ├── code-modernizer/
+│   └── quality-pipeline/
+├── server/               ← Express API bridge (port 3002)
+├── client/               ← Vite + React UI (port 5177)
+└── demo/
+    └── legacy-app/src/   ← Sample JS project for Code Modernizer + Quality Pipeline demos
+```
+
+It's an npm workspace. `npm install` at the root installs everything. Each package builds independently with `tsc`.
+
+---
+
+## In Production: Where the AI Fits In
+
+DevForge demos the tools layer in isolation. But in a real MCP setup, an AI model sits between the user and the tools:
+
+```
+User: "Review my Button component and fix any issues"
+                    ↓
+              Claude (or any LLM)
+                    ↓
+    Decides to call: review_component({ path: '/src/Button' })
+                    ↓
+              Component Factory tool
+                    ↓
+    Returns: { grade: "C", issues: ["missing displayName", "broken import"] }
+                    ↓
+    Decides to call: fix_component({ path: '/src/Button' })
+                    ↓
+              Component Factory tool
+                    ↓
+    Returns: { fixed: true, changes: [...] }
+                    ↓
+Claude: "Done — fixed 2 issues: added displayName and corrected the import path"
+```
+
+The AI doesn't write the code or run the analysis. It just decides *which tool to call* and *with what arguments*, based on the user's intent. The tools do the actual work — exactly as you've seen in this demo.

package/README.md

@@ -0,0 +1,259 @@
+# mcp-toolkit
+
+MCP servers for React + TypeScript development automation. Works with Claude Desktop, Cline, Cursor — and as plain CLI scripts — one protocol, zero duplication.
+
+[![CI](https://github.com/Nishant-Chaudhary5338/mcp-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Nishant-Chaudhary5338/mcp-toolkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12.0-blue)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Tests](https://img.shields.io/badge/tests-134%20passing-brightgreen)](#testing)
+
+---
+
+## What's here
+
+```
+tools/      9 MCP server packages — each independently buildable and runnable
+server/     Express bridge (port 3002) — proxies calls from the UI to MCP servers
+client/     React 19 showcase SPA — tool catalog, workflow demos, animated flowcharts
+```
+
+---
+
+## Tools
+
+All 9 tools are production-ready: built, tested, and CI-verified on Node 20 + 22.
+
+| Tool | What it does | MCP tools exposed |
+|---|---|---|
+| `component-factory` | Scaffold React components from 41 shadcn/ui templates — with tests + Storybook | 6 |
+| `code-modernizer` | AST-based JS/JSX → TypeScript conversion, PropTypes → interfaces | 1 |
+| `quality-pipeline` | 5-stage audit (tests · types · perf · a11y · design tokens) graded A–F | 2 |
+| `json-viewer` | Generate an interactive HTML JSON viewer — collapsible, searchable, dark/light | 3 |
+| `dep-auditor` | Unused deps, duplicate versions, circular imports, bundle impact analysis | 4 |
+| `accessibility-checker` | WCAG 2.1 audit — alt text, label associations, ARIA roles, keyboard navigation | 3 |
+| `generate-tests` | Analyze a TypeScript/React source file and generate a Vitest test suite | 2 |
+| `typescript-enforcer` | Scan for `any` types, unsafe casts, missing modifiers — 7 rules, scored 0–10 | 4 |
+| `monorepo-manager` | Workspace listing, dependency graph, health check, shared dep finder | 6 |
+
+### Roadmap
+
+| Tool | Description | Status |
+|---|---|---|
+| `render-analyzer` | React render profiling — detect unnecessary renders, missing memo | 📋 Planned |
+| `storybook-generator` | Auto-generate Storybook stories for existing components | 📋 Planned |
+| `legacy-analyzer` | Tech debt detection — anti-patterns, duplication, refactor plans | 📋 Planned |
+| `test-gap-analyzer` | Find unimplemented functions, uncovered branches, missing edge cases | 📋 Planned |
+| `performance-audit` | Bundle size analysis, memory leaks, slow component detection | 📋 Planned |
+| `lighthouse-runner` | Web Vitals / Lighthouse audit via CLI | 📋 Planned |
+| `component-reviewer` | Audit TypeScript errors, test coverage gaps, a11y issues | 📋 Planned |
+| `component-fixer` | Auto-fix broken imports, missing dependencies, export corrections | 📋 Planned |
+
+Want to implement one of these? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Automation workflows
+
+### 1 · Code Modernization
+```
+legacy-analyzer → code-modernizer → typescript-enforcer → generate-tests
+```
+Migrate a JS codebase to strict TypeScript with auto-generated test coverage.
+
+### 2 · Dependency Health
+```
+dep-auditor [unused] → dep-auditor [duplicates] → dep-auditor [bundle-impact] → monorepo-manager
+```
+Audit and clean up a monorepo's dependency graph end-to-end.
+
+### 3 · Component Pipeline
+```
+component-factory → accessibility-checker → quality-pipeline
+```
+Generate a production-ready component and verify it before shipping.
+
+### 4 · Quality Audit
+```
+accessibility-checker → typescript-enforcer → quality-pipeline
+```
+Full code quality check — WCAG compliance, type safety score, overall grade.
+
+---
+
+## How MCP works
+
+```
+Claude Desktop / Cline / Cursor
+        │
+        │ JSON-RPC over stdio
+        ▼
+   MCP Server (e.g. typescript-enforcer)
+        │
+        ▼
+   Tool handlers (your code)
+```
+
+Each server in this repo extends `McpServerBase` from `tools/shared/` — an abstract class that handles transport, routing, and error formatting. Adding a new tool is ~50 lines.
+
+```typescript
+import { McpServerBase } from '@mcp-showcase/shared';
+
+class MyTool extends McpServerBase {
+  constructor() {
+    super({ name: 'my-tool', version: '1.0.0' });
+  }
+
+  protected registerTools(): void {
+    this.addTool('do_thing', 'Does a thing', {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'Target path' } },
+      required: ['path'],
+    }, async (args) => {
+      const { path } = args as { path: string };
+      return this.success({ result: `Processed ${path}` });
+    });
+  }
+}
+
+new MyTool().run();
+```
+
+---
+
+## Run locally
+
+```sh
+git clone https://github.com/Nishant-Chaudhary5338/mcp-toolkit.git
+cd mcp-toolkit
+npm install
+npm run build
+npm test          # 134 tests across all 9 tools
+npm run dev       # server on :3002, client on :5173
+```
+
+### Add to Claude Desktop
+
+```jsonc
+// ~/Library/Application Support/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "component-factory": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/component-factory/build/index.js"]
+    },
+    "code-modernizer": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/code-modernizer/build/index.js"]
+    },
+    "quality-pipeline": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/quality-pipeline/build/index.js"]
+    },
+    "json-viewer": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/json-viewer/build/index.js"]
+    },
+    "dep-auditor": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/dep-auditor/build/index.js"]
+    },
+    "accessibility-checker": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/accessibility-checker/build/index.js"]
+    },
+    "generate-tests": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/generate-tests/build/index.js"]
+    },
+    "typescript-enforcer": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/typescript-enforcer/build/index.js"]
+    },
+    "monorepo-manager": {
+      "command": "node",
+      "args": ["/path/to/mcp-toolkit/tools/monorepo-manager/build/index.js"]
+    }
+  }
+}
+```
+
+### Use as a CLI / in CI
+
+```sh
+# Scan a file for TypeScript issues
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"scan_file","arguments":{"path":"src/App.tsx"}}}' \
+  | node tools/typescript-enforcer/build/index.js
+
+# Run a full WCAG audit
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_accessibility","arguments":{"path":"src/components"}}}' \
+  | node tools/accessibility-checker/build/index.js
+```
+
+---
+
+## Testing
+
+Each tool has a dedicated test file covering its core logic directly — no MCP transport required.
+
+```sh
+npm test                                    # all tools
+npm run test -w tools/typescript-enforcer  # single tool
+```
+
+| Tool | Tests |
+|---|---|
+| json-viewer | 16 |
+| quality-pipeline | 8 |
+| component-factory | 6 |
+| code-modernizer | 8 |
+| dep-auditor | 15 |
+| accessibility-checker | 15 |
+| generate-tests | 14 |
+| typescript-enforcer | 22 |
+| monorepo-manager | 30 |
+
+CI runs on every push and PR against Node 20 and 22.
+
+---
+
+## Architecture
+
+```
+tools/
+  shared/                McpServerBase, ToolRegistry, shared types
+  component-factory/     41 shadcn/ui templates
+  code-modernizer/       AST-based TS conversion
+  quality-pipeline/      5-stage grading system
+  json-viewer/           HTML generation
+  dep-auditor/           Dependency graph analysis
+  accessibility-checker/ WCAG rule engine (9 rules)
+  generate-tests/        Source analyzer + test generator
+  typescript-enforcer/   7-rule type safety scanner
+  monorepo-manager/      Workspace operations
+
+server/                  Express bridge — spawns tools as child processes
+client/                  React 19 SPA — tool catalog and live demos
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — how to scaffold a new tool, write tests, and open a PR.
+
+---
+
+## Stack
+
+TypeScript strict · Node.js · MCP SDK 1.12 · Vitest · React 19 · Vite · Tailwind CSS · Express
+
+---
+
+## Built by
+
+**Nishant Chaudhary** — Senior Frontend Engineer  
+nishantchaudhary.dev@gmail.com
+
+**Also see:** [dashcraft](https://github.com/Nishant-Chaudhary5338/dashcraft) · [react-present](https://github.com/Nishant-Chaudhary5338/react-present) · [ai-builder](https://github.com/Nishant-Chaudhary5338/ai-builder)
+
+MIT License

package/demo/legacy-app/src/App.jsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import Dashboard from './components/Dashboard';
+
+function App() {
+  return (
+    <div className="app">
+      <Dashboard title="User Management" currentUser="Admin" />
+    </div>
+  );
+}
+
+export default App;