@dewtech/dare-cli 3.0.0 → 3.1.0

package/templates/stacks/mcp-node-ts/README.md.hbs

@@ -0,0 +1,49 @@
+# {{projectName}}
+
+DARE-shaped MCP (Model Context Protocol) server in TypeScript.
+Default transport: **{{defaultTransport}}**.
+
+## Setup
+
+```bash
+cp .env.example .env
+pnpm install
+pnpm build
+pnpm start                # uses {{defaultTransport}} transport (default)
+```
+
+## Test it with MCP Inspector
+
+```bash
+pnpm inspect              # spawns the server + opens the inspector UI
+```
+
+## Tools
+
+- `echo` — returns its input. The canonical smoke test for an MCP server.
+
+## Prompts
+
+- `summarize` — placeholder prompt template that takes a `{text}` variable.
+
+## Transports
+
+Pick at runtime via `--transport stdio|sse|http` or `MCP_TRANSPORT` env:
+
+| Transport | When to use |
+|---|---|
+| `stdio` (default) | Local CLI agents (Claude Code, Cursor, etc.) |
+| `sse`             | Web clients via Server-Sent Events |
+| `http`            | Streamable HTTP — newest MCP transport |
+
+## Commands
+
+- `pnpm dev` — watch mode via tsx
+- `pnpm build` — TypeScript → `dist/`
+- `pnpm test` — vitest
+- `pnpm lint` — ESLint
+- `pnpm audit` — `pnpm audit --audit-level=high`
+
+## DARE Method
+
+See `.dare/skills.yml` and `llms.txt`.

package/templates/stacks/mcp-node-ts/gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+coverage
+.env
+.env.local
+*.log
+.DS_Store

package/templates/stacks/mcp-node-ts/llms.txt.hbs

@@ -0,0 +1,61 @@
+# {{projectName}}
+
+DARE-shaped MCP server (TypeScript). Default transport: **{{defaultTransport}}**.
+
+## Setup
+
+```bash
+cp .env.example .env
+pnpm install
+pnpm build
+pnpm start
+```
+
+## Commands
+
+- `pnpm dev` — tsx watch
+- `pnpm build` — tsc to dist/
+- `pnpm test` — vitest
+- `pnpm lint` — ESLint
+- `pnpm audit` — pnpm audit --audit-level=high
+- `pnpm inspect` — MCP Inspector for the running server
+
+## Tools (registered in src/tools/)
+
+| Name | Input | Output | Description |
+|---|---|---|---|
+| `echo` | `{ text: string }` | `{ text: string }` | Returns input verbatim. Smoke test. |
+
+## Prompts (registered in src/prompts/)
+
+| Name | Args | Description |
+|---|---|---|
+| `summarize` | `{ text }` | Summarize the input text. Placeholder. |
+
+## Transports
+
+Choose with `--transport stdio|sse|http` or `MCP_TRANSPORT`:
+
+- `stdio` (default) — local agents. No port. 1 client at a time.
+- `sse` — SSE-over-HTTP on `MCP_PORT` (default 3001).
+- `http` — Streamable HTTP on `MCP_PORT` (default 3001). Modern MCP HTTP.
+
+## Architecture
+
+- `src/server.ts` — MCP `Server` instance, tools and prompts registered here.
+- `src/cli.ts` — entrypoint. Resolves transport from CLI flag or env.
+- `src/transports/{stdio,sse,http}.ts` — one factory per transport.
+- `src/tools/`, `src/prompts/` — registries the server reads from.
+
+## Env vars
+
+See `.env.example`. None are required for stdio.
+
+## CLI inventory
+
+`node dist/cli.js --json --list-tools` returns the tool registry as JSON
+(M-03 — Agent eXperience).
+
+## DARE skills
+
+See `.dare/skills.yml`.

package/templates/stacks/mcp-node-ts/openapi.json.hbs

@@ -0,0 +1,39 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "{{projectName}}",
+    "version": "0.1.0",
+    "description": "MCP server JSON-RPC surface. MCP itself is not a REST API; this document describes the HTTP/SSE transport envelope. Stdio transport is out of band."
+  },
+  "paths": {
+    "/mcp/v1/sse": {
+      "get": {
+        "summary": "MCP SSE transport — long-lived event stream",
+        "responses": {
+          "200": { "description": "text/event-stream with MCP JSON-RPC frames" }
+        }
+      }
+    },
+    "/mcp/v1/messages": {
+      "post": {
+        "summary": "MCP JSON-RPC message (HTTP transport)",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "type": "object", "description": "JSON-RPC 2.0 request" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "JSON-RPC 2.0 response",
+            "content": {
+              "application/json": { "schema": { "type": "object" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/stacks/mcp-node-ts/package.json.hbs

@@ -0,0 +1,35 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "DARE-shaped MCP server (Node.js / TypeScript)",
+  "type": "module",
+  "bin": {
+    "{{projectName}}": "dist/cli.js"
+  },
+  "main": "dist/server.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsx watch src/cli.ts",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "audit": "pnpm audit --audit-level=high",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "express": "^4.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}

package/templates/stacks/mcp-node-ts/src/cli.ts.hbs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { TOOLS } from './tools/index.js';
+import { createServer } from './server.js';
+import { createStdioTransport } from './transports/stdio.js';
+import { startSseTransport } from './transports/sse.js';
+import { startHttpTransport } from './transports/http.js';
+
+type Transport = 'stdio' | 'sse' | 'http';
+
+interface Args {
+  transport: Transport;
+  listToolsJson: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  let transport: Transport =
+    (process.env.MCP_TRANSPORT as Transport | undefined) ?? '{{defaultTransport}}';
+  let listToolsJson = false;
+  let json = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--transport' && argv[i + 1]) {
+      const next = argv[++i];
+      if (next === 'stdio' || next === 'sse' || next === 'http') {
+        transport = next;
+      } else {
+        throw new Error(`invalid --transport '${next}' (valid: stdio, sse, http)`);
+      }
+    } else if (a === '--json') {
+      json = true;
+    } else if (a === '--list-tools') {
+      listToolsJson = true;
+    }
+  }
+
+  return { transport, listToolsJson: listToolsJson && json };
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.listToolsJson) {
+    process.stdout.write(JSON.stringify({ tools: TOOLS }, null, 2) + '\n');
+    return;
+  }
+
+  const server = createServer();
+  const port = Number(process.env.MCP_PORT ?? 3001);
+
+  switch (args.transport) {
+    case 'stdio': {
+      const transport = createStdioTransport();
+      await server.connect(transport);
+      return;
+    }
+    case 'sse': {
+      await startSseTransport(server, port);
+      return;
+    }
+    case 'http': {
+      await startHttpTransport(server, port);
+      return;
+    }
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[mcp] fatal: ${(err as Error).message}\n`);
+  process.exit(1);
+});

package/templates/stacks/mcp-node-ts/src/prompts/index.ts

@@ -0,0 +1,36 @@
+import type { Prompt } from '@modelcontextprotocol/sdk/types.js';
+
+export const PROMPTS: Prompt[] = [
+  {
+    name: 'summarize',
+    description: 'Summarize the given text in 1-2 sentences.',
+    arguments: [
+      {
+        name: 'text',
+        description: 'Text to summarize',
+        required: true,
+      },
+    ],
+  },
+];
+
+export async function getPrompt(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<{ messages: Array<{ role: 'user'; content: { type: 'text'; text: string } }> }> {
+  if (name === 'summarize') {
+    const text = String(args.text ?? '');
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Summarize the following text in 1-2 sentences.\n\n${text}`,
+          },
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown prompt: ${name}`);
+}

package/templates/stacks/mcp-node-ts/src/server.ts.hbs

@@ -0,0 +1,45 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { TOOLS, callTool } from './tools/index.js';
+import { PROMPTS, getPrompt } from './prompts/index.js';
+
+export function createServer(): Server {
+  const server = new Server(
+    {
+      name: '{{projectName}}',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+        prompts: {},
+      },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    return callTool(name, args ?? {});
+  });
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: PROMPTS,
+  }));
+
+  server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    return getPrompt(name, args ?? {});
+  });
+
+  return server;
+}

package/templates/stacks/mcp-node-ts/src/tools/echo.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const echoInput = z.object({
+  text: z.string().min(1, 'text is required'),
+});
+
+export const echoTool: Tool = {
+  name: 'echo',
+  description: 'Returns its input. Canonical smoke test for an MCP server.',
+  inputSchema: {
+    type: 'object',
+    required: ['text'],
+    properties: {
+      text: { type: 'string', minLength: 1, description: 'Text to echo back' },
+    },
+  },
+};
+
+export async function runEcho(args: unknown): Promise<string> {
+  const parsed = echoInput.parse(args);
+  return parsed.text;
+}

package/templates/stacks/mcp-node-ts/src/tools/index.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { echoTool, runEcho } from './echo.js';
+
+export const TOOLS: Tool[] = [echoTool];
+
+export async function callTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+  if (name === echoTool.name) {
+    const text = await runEcho(args);
+    return { content: [{ type: 'text', text }] };
+  }
+  return {
+    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+    isError: true,
+  };
+}

package/templates/stacks/mcp-node-ts/src/transports/http.ts

@@ -0,0 +1,68 @@
+import express from 'express';
+import { randomUUID } from 'node:crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+/**
+ * Streamable HTTP — modern MCP HTTP transport. Each client gets its own
+ * session keyed by Mcp-Session-Id header (auto-generated on initialize).
+ */
+export async function startHttpTransport(server: Server, port: number): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  // Rate limit (same shape as SSE) — apply if RATE_LIMIT_RPM is set.
+  const rpm = Number(process.env.RATE_LIMIT_RPM ?? 0);
+  if (rpm > 0) {
+    const seen = new Map<string, { count: number; resetAt: number }>();
+    app.use((req, res, next) => {
+      const ip = req.ip ?? 'unknown';
+      const now = Date.now();
+      const entry = seen.get(ip);
+      if (!entry || entry.resetAt < now) {
+        seen.set(ip, { count: 1, resetAt: now + 60_000 });
+        return next();
+      }
+      if (entry.count >= rpm) {
+        res.status(429).json({ error: 'rate limit exceeded' });
+        return;
+      }
+      entry.count += 1;
+      next();
+    });
+  }
+
+  const transports = new Map<string, StreamableHTTPServerTransport>();
+
+  app.post('/mcp/v1/messages', async (req, res) => {
+    const sessionId = req.header('mcp-session-id');
+    let transport = sessionId ? transports.get(sessionId) : undefined;
+    if (!transport) {
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (id: string) => {
+          transports.set(id, transport!);
+        },
+      });
+      await server.connect(transport);
+    }
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.get('/mcp/v1/messages', async (req, res) => {
+    const sessionId = req.header('mcp-session-id');
+    const transport = sessionId ? transports.get(sessionId) : undefined;
+    if (!transport) {
+      res.status(400).json({ error: 'no active session' });
+      return;
+    }
+    await transport.handleRequest(req, res);
+  });
+
+  await new Promise<void>((resolve) => {
+    app.listen(port, () => {
+      process.stderr.write(`[mcp/http] listening on :${port}\n`);
+      resolve();
+    });
+  });
+}

package/templates/stacks/mcp-node-ts/src/transports/sse.ts

@@ -0,0 +1,58 @@
+import express from 'express';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+
+/**
+ * Legacy MCP SSE transport. Holds one SSE connection at a time; multiple
+ * clients require running multiple server instances behind a load balancer.
+ *
+ * For new deployments prefer the modern Streamable HTTP transport
+ * (transports/http.ts) — SSE is kept here for compatibility with older
+ * MCP clients that only speak the SSE wire format.
+ */
+export async function startSseTransport(server: Server, port: number): Promise<void> {
+  const app = express();
+
+  // Rate limit knob — apply if RATE_LIMIT_RPM is set. Simple token bucket per IP.
+  const rpm = Number(process.env.RATE_LIMIT_RPM ?? 0);
+  if (rpm > 0) {
+    const seen = new Map<string, { count: number; resetAt: number }>();
+    app.use((req, res, next) => {
+      const ip = req.ip ?? 'unknown';
+      const now = Date.now();
+      const entry = seen.get(ip);
+      if (!entry || entry.resetAt < now) {
+        seen.set(ip, { count: 1, resetAt: now + 60_000 });
+        return next();
+      }
+      if (entry.count >= rpm) {
+        res.status(429).json({ error: 'rate limit exceeded' });
+        return;
+      }
+      entry.count += 1;
+      next();
+    });
+  }
+
+  let transport: SSEServerTransport | null = null;
+
+  app.get('/mcp/v1/sse', async (_req, res) => {
+    transport = new SSEServerTransport('/mcp/v1/messages', res);
+    await server.connect(transport);
+  });
+
+  app.post('/mcp/v1/messages', express.json(), async (req, res) => {
+    if (!transport) {
+      res.status(400).json({ error: 'no active SSE session' });
+      return;
+    }
+    await transport.handlePostMessage(req, res, req.body);
+  });
+
+  await new Promise<void>((resolve) => {
+    app.listen(port, () => {
+      process.stderr.write(`[mcp/sse] listening on :${port}\n`);
+      resolve();
+    });
+  });
+}

package/templates/stacks/mcp-node-ts/src/transports/stdio.ts

@@ -0,0 +1,5 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+export function createStdioTransport(): StdioServerTransport {
+  return new StdioServerTransport();
+}

package/templates/stacks/mcp-node-ts/tests/echo.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { runEcho, echoTool } from '../src/tools/echo.js';
+import { TOOLS, callTool } from '../src/tools/index.js';
+import { PROMPTS, getPrompt } from '../src/prompts/index.js';
+
+describe('echo tool', () => {
+  it('is registered in TOOLS', () => {
+    expect(TOOLS).toContain(echoTool);
+  });
+
+  it('returns its input verbatim', async () => {
+    const out = await runEcho({ text: 'hello' });
+    expect(out).toBe('hello');
+  });
+
+  it('rejects empty text', async () => {
+    await expect(runEcho({ text: '' })).rejects.toThrow();
+  });
+
+  it('rejects missing text', async () => {
+    await expect(runEcho({})).rejects.toThrow();
+  });
+
+  it('callTool routes to echo', async () => {
+    const res = await callTool('echo', { text: 'hi' });
+    expect(res.content[0].text).toBe('hi');
+    expect(res.isError).toBeFalsy();
+  });
+
+  it('callTool returns isError for unknown tool', async () => {
+    const res = await callTool('unknown', {});
+    expect(res.isError).toBe(true);
+  });
+});
+
+describe('summarize prompt', () => {
+  it('is registered in PROMPTS', () => {
+    expect(PROMPTS.some((p) => p.name === 'summarize')).toBe(true);
+  });
+
+  it('returns a user message with the input text', async () => {
+    const res = await getPrompt('summarize', { text: 'long text here' });
+    expect(res.messages[0].role).toBe('user');
+    expect(res.messages[0].content.text).toContain('long text here');
+  });
+
+  it('throws on unknown prompt', async () => {
+    await expect(getPrompt('unknown', {})).rejects.toThrow();
+  });
+});

package/templates/stacks/mcp-node-ts/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/templates/stacks/mcp-python/.dare/skills.yml

@@ -0,0 +1,8 @@
+version: 1
+skills:
+  - id: skill-mcp-server
+    source: skill-mcp-server
+    description: MCP server patterns (tools, prompts, transports)
+  - id: dare-ax
+    source: dare-ax
+    description: Agent eXperience invariants (llms.txt, OpenAPI, --json --list-tools, rate limit)

package/templates/stacks/mcp-python/.env.example

@@ -0,0 +1,14 @@
+# MCP transport — overrides --transport flag if set
+# Valid: stdio | sse | http
+MCP_TRANSPORT=stdio
+
+# HTTP/SSE transport port (ignored on stdio)
+MCP_PORT=3001
+MCP_HOST=0.0.0.0
+
+# Logging
+LOG_LEVEL=info
+
+# LLM provider (optional)
+LLM_PROVIDER=dummy
+# OPENAI_API_KEY=

package/templates/stacks/mcp-python/.github/workflows/dare-ci.yml

@@ -0,0 +1,42 @@
+name: DARE CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  audit:
+    name: pip-audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install pip-audit
+      - run: pip install -e ".[dev]"
+      - run: pip-audit --strict
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check .
+
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: pytest