@dewtech/dare-cli 2.17.0 → 3.1.0

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

package/templates/stacks/mcp-python/README.md.j2

@@ -0,0 +1,49 @@
+# {{ projectName }}
+
+DARE-shaped MCP server in Python 3.11+ using the FastMCP API.
+Default transport: **{{ defaultTransport }}**.
+
+## Setup
+
+```bash
+cp .env.example .env
+python -m venv .venv
+source .venv/bin/activate    # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+python -m src.cli            # uses {{ defaultTransport }} transport by default
+```
+
+## Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector python -m src.cli
+```
+
+## Tools
+
+- `echo` — returns its input. Canonical smoke test.
+
+## Prompts
+
+- `summarize` — placeholder prompt template that takes a `text` argument.
+
+## Transports
+
+Pick at runtime via `--transport stdio|sse|http` or `MCP_TRANSPORT` env:
+
+| Transport | When to use |
+|---|---|
+| `stdio` (default) | Local CLI agents |
+| `sse`             | Web clients via Server-Sent Events |
+| `http`            | Streamable HTTP — newest MCP transport |
+
+## Commands
+
+- `python -m src.cli` — start server
+- `pytest` — run tests
+- `ruff check .` — lint
+- `pip-audit` — dependency audit
+
+## DARE Method
+
+See `.dare/skills.yml` and `llms.txt`.

package/templates/stacks/mcp-python/gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.env
+.env.local
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+*.egg-info/
+.DS_Store

package/templates/stacks/mcp-python/llms.txt.j2

@@ -0,0 +1,56 @@
+# {{ projectName }}
+
+DARE-shaped MCP server (Python 3.11+). Default transport: **{{ defaultTransport }}**.
+
+## Setup
+
+```bash
+cp .env.example .env
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+python -m src.cli
+```
+
+## Commands
+
+- `python -m src.cli` — start server (transport via --transport or MCP_TRANSPORT env)
+- `pytest` — pytest suite
+- `ruff check .` — lint
+- `pip-audit` — dependency audit
+- `npx @modelcontextprotocol/inspector python -m src.cli` — MCP Inspector
+
+## Tools (registered in src/server.py via FastMCP)
+
+| Name | Input | Output | Description |
+|---|---|---|---|
+| `echo` | `text: str` | `str` | Returns input verbatim. Smoke test. |
+
+## 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.
+- `sse` — SSE-over-HTTP on `MCP_PORT` (default 3001).
+- `http` — Streamable HTTP on `MCP_PORT` (default 3001).
+
+## Architecture
+
+- `src/server.py` — FastMCP instance, tools and prompts registered with @mcp.tool() / @mcp.prompt().
+- `src/cli.py` — argparse entrypoint, transport dispatch.
+- `src/transports/` — wrappers around mcp.run() calls for the 3 transports.
+- `src/tools/`, `src/prompts/` — module per tool/prompt for organization.
+
+## CLI inventory
+
+`python -m src.cli --json --list-tools` returns the tool registry as JSON (M-03).
+
+## DARE skills
+
+See `.dare/skills.yml`.

package/templates/stacks/mcp-python/openapi.json.j2

@@ -0,0 +1,33 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "{{ projectName }}",
+    "version": "0.1.0",
+    "description": "MCP server JSON-RPC surface. MCP is not REST; this describes the HTTP/SSE transport envelopes only."
+  },
+  "paths": {
+    "/sse": {
+      "get": {
+        "summary": "SSE event stream",
+        "responses": { "200": { "description": "text/event-stream with MCP JSON-RPC frames" } }
+      }
+    },
+    "/messages": {
+      "post": {
+        "summary": "MCP JSON-RPC message (HTTP / SSE post-back)",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "type": "object" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "JSON-RPC 2.0 response",
+            "content": { "application/json": { "schema": { "type": "object" } } }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/stacks/mcp-python/pyproject.toml.j2

@@ -0,0 +1,37 @@
+[project]
+name = "{{ projectName }}"
+version = "0.1.0"
+description = "DARE-shaped MCP server (Python)"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.0.0,<2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2,<9.0",
+    "pytest-asyncio>=0.23,<1.0",
+    "ruff>=0.5,<1.0",
+    "pip-audit>=2.7,<3.0",
+]
+
+[project.scripts]
+{{ projectModule }} = "src.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

package/templates/stacks/mcp-python/src/cli.py.j2

@@ -0,0 +1,68 @@
+"""CLI entrypoint — picks transport from --transport or MCP_TRANSPORT env."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Literal
+
+from src.server import mcp
+from src.transports import http as http_transport
+from src.transports import sse as sse_transport
+from src.transports import stdio as stdio_transport
+
+Transport = Literal["stdio", "sse", "http"]
+
+
+def parse_args(argv: list[str]) -> tuple[Transport, bool]:
+    env_default = os.environ.get("MCP_TRANSPORT", "{{ defaultTransport }}")
+    parser = argparse.ArgumentParser(description="DARE-shaped MCP server")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "http"],
+        default=env_default,
+        help="Transport (default: %(default)s)",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON output (use with --list-tools)")
+    parser.add_argument("--list-tools", action="store_true", help="List registered tools as JSON and exit")
+    ns = parser.parse_args(argv)
+    return ns.transport, bool(ns.json and ns.list_tools)
+
+
+def list_tools_json() -> None:
+    # FastMCP keeps an in-memory registry; surface it as a stable JSON shape.
+    tools = [
+        {
+            "name": name,
+            "description": (t.description or "").strip(),
+            # FastMCP's Tool exposes the JSON schema as `parameters`.
+            "inputSchema": t.parameters,
+        }
+        for name, t in mcp._tool_manager._tools.items()  # type: ignore[attr-defined]
+    ]
+    sys.stdout.write(json.dumps({"tools": tools}, indent=2) + "\n")
+
+
+def main(argv: list[str] | None = None) -> None:
+    transport, want_list = parse_args(sys.argv[1:] if argv is None else argv)
+
+    if want_list:
+        list_tools_json()
+        return
+
+    port = int(os.environ.get("MCP_PORT", "3001"))
+    host = os.environ.get("MCP_HOST", "0.0.0.0")
+
+    if transport == "stdio":
+        stdio_transport.run(mcp)
+    elif transport == "sse":
+        sse_transport.run(mcp, host=host, port=port)
+    elif transport == "http":
+        http_transport.run(mcp, host=host, port=port)
+    else:  # pragma: no cover — argparse guarantees one of the above
+        raise SystemExit(f"invalid transport: {transport}")
+
+
+if __name__ == "__main__":
+    main()

package/templates/stacks/mcp-python/src/prompts/summarize.py

@@ -0,0 +1,10 @@
+"""Summarize prompt — returns a templated user message."""
+
+
+def summarize(text: str) -> str:
+    """Returns the user message body for a summarize prompt.
+
+    Args:
+        text: Text to summarize.
+    """
+    return f"Summarize the following text in 1-2 sentences.\n\n{text}"

package/templates/stacks/mcp-python/src/server.py.j2

@@ -0,0 +1,28 @@
+"""FastMCP server — tools and prompts registered here."""
+from mcp.server.fastmcp import FastMCP
+
+from src.tools.echo import echo as echo_impl
+from src.prompts.summarize import summarize as summarize_impl
+
+
+mcp = FastMCP("{{ projectName }}")
+
+
+@mcp.tool()
+async def echo(text: str) -> str:
+    """Returns its input. Canonical smoke test for an MCP server.
+
+    Args:
+        text: Text to echo back (required, non-empty).
+    """
+    return await echo_impl(text)
+
+
+@mcp.prompt()
+def summarize(text: str) -> str:
+    """Summarize the given text in 1-2 sentences.
+
+    Args:
+        text: Text to summarize.
+    """
+    return summarize_impl(text)

package/templates/stacks/mcp-python/src/tools/echo.py

@@ -0,0 +1,12 @@
+"""Echo tool implementation — testable as a plain function."""
+
+
+async def echo(text: str) -> str:
+    """Returns its input verbatim.
+
+    Raises:
+        ValueError: when text is empty or None.
+    """
+    if not isinstance(text, str) or not text:
+        raise ValueError("text must be a non-empty string")
+    return text