@dewtech/dare-cli 3.0.0 → 3.2.0

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

package/templates/stacks/mcp-python/src/transports/http.py

@@ -0,0 +1,12 @@
+"""Streamable HTTP transport — modern MCP HTTP wire format.
+
+Each client gets its own session keyed by the Mcp-Session-Id header,
+generated on initialize. FastMCP wraps the uvicorn + Starlette plumbing.
+"""
+from mcp.server.fastmcp import FastMCP
+
+
+def run(mcp: FastMCP, host: str = "0.0.0.0", port: int = 3001) -> None:
+    mcp.settings.host = host
+    mcp.settings.port = port
+    mcp.run(transport="streamable-http")

package/templates/stacks/mcp-python/src/transports/sse.py

@@ -0,0 +1,13 @@
+"""SSE-over-HTTP transport — legacy MCP HTTP wire format.
+
+FastMCP launches a uvicorn server under the hood and exposes the SSE
+endpoints. For new deployments prefer the streamable HTTP transport
+(transports/http.py).
+"""
+from mcp.server.fastmcp import FastMCP
+
+
+def run(mcp: FastMCP, host: str = "0.0.0.0", port: int = 3001) -> None:
+    mcp.settings.host = host
+    mcp.settings.port = port
+    mcp.run(transport="sse")

package/templates/stacks/mcp-python/src/transports/stdio.py

@@ -0,0 +1,6 @@
+"""stdio transport — the default for local agents."""
+from mcp.server.fastmcp import FastMCP
+
+
+def run(mcp: FastMCP) -> None:
+    mcp.run(transport="stdio")

package/templates/stacks/mcp-python/tests/test_echo.py

@@ -0,0 +1,28 @@
+"""Smoke tests for echo tool and summarize prompt."""
+import pytest
+
+from src.prompts.summarize import summarize
+from src.tools.echo import echo
+
+
+@pytest.mark.asyncio
+async def test_echo_returns_input():
+    assert await echo("hello") == "hello"
+
+
+@pytest.mark.asyncio
+async def test_echo_rejects_empty():
+    with pytest.raises(ValueError):
+        await echo("")
+
+
+@pytest.mark.asyncio
+async def test_echo_rejects_non_string():
+    with pytest.raises(ValueError):
+        await echo(None)  # type: ignore[arg-type]
+
+
+def test_summarize_includes_input_text():
+    out = summarize("long text here")
+    assert "long text here" in out
+    assert "Summarize" in out

package/templates/stacks/mcp-rust/.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-rust/.env.example

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

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

@@ -0,0 +1,38 @@
+name: DARE CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  audit:
+    name: cargo audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo install cargo-audit --locked
+      - run: cargo audit --deny warnings
+
+  lint:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets -- -D warnings
+
+  test:
+    name: cargo test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test

package/templates/stacks/mcp-rust/Cargo.toml.tera

@@ -0,0 +1,35 @@
+[package]
+name = "{{ crateName }}"
+version = "0.1.0"
+edition = "2021"
+description = "DARE-shaped MCP server (Rust)"
+license = "MIT"
+
+[dependencies]
+# Official Rust MCP SDK. API still stabilizing — pin a rev if upstream breaks.
+rmcp = { version = "0.1", features = ["server", "transport-io"] }
+
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# HTTP/SSE transports
+axum = { version = "0.7", features = ["macros"] }
+tower-http = { version = "0.6", features = ["cors"] }
+
+# CLI args
+clap = { version = "4", features = ["derive", "env"] }
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+anyhow = "1"
+thiserror = "1"
+
+[dev-dependencies]
+tokio-test = "0.4"
+
+[[bin]]
+name = "{{ crateName }}"
+path = "src/main.rs"

package/templates/stacks/mcp-rust/README.md.tera

@@ -0,0 +1,50 @@
+# {{ projectName }}
+
+DARE-shaped MCP server in Rust using the `rmcp` SDK.
+Default transport: **{{ defaultTransport }}**.
+
+> ⚠️ **Beta.** The `rmcp` SDK API is still stabilizing. Pin a specific version
+> or git rev in `Cargo.toml` if an upstream release breaks the build.
+
+## Setup
+
+```bash
+cp .env.example .env
+cargo build
+cargo run                    # uses {{ defaultTransport }} transport by default
+```
+
+## Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector cargo run
+```
+
+## Tools
+
+- `echo` — returns its input. Canonical smoke test.
+
+## Prompts
+
+- `summarize` — placeholder prompt template taking a `text` argument.
+
+## Transports
+
+Pick at runtime via `--transport stdio|sse|http` or `MCP_TRANSPORT`:
+
+| Transport | When to use |
+|---|---|
+| `stdio` (default) | Local CLI agents |
+| `sse`             | Web clients via SSE (axum) |
+| `http`            | Streamable HTTP (axum) |
+
+## Commands
+
+- `cargo run` — start server
+- `cargo test` — tests
+- `cargo clippy -- -D warnings` — lint
+- `cargo audit` — dependency audit
+
+## DARE Method
+
+See `.dare/skills.yml` and `llms.txt`.

package/templates/stacks/mcp-rust/gitignore

@@ -0,0 +1,5 @@
+/target
+.env
+.env.local
+*.log
+.DS_Store

package/templates/stacks/mcp-rust/llms.txt.tera

@@ -0,0 +1,60 @@
+# {{ projectName }}
+
+DARE-shaped MCP server (Rust, rmcp SDK). Default transport: **{{ defaultTransport }}**. BETA.
+
+## Setup
+
+```bash
+cp .env.example .env
+cargo build
+cargo run
+```
+
+## Commands
+
+- `cargo run` — start server (transport via --transport or MCP_TRANSPORT env)
+- `cargo test` — tests
+- `cargo clippy -- -D warnings` — lint
+- `cargo audit` — RustSec advisory audit
+- `npx @modelcontextprotocol/inspector cargo run` — MCP Inspector
+
+## Tools (registered in src/server.rs)
+
+| Name | Input | Output | Description |
+|---|---|---|---|
+| `echo` | `text: String` | `String` | 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), served by axum.
+- `http` — Streamable HTTP on MCP_PORT, served by axum.
+
+## Architecture
+
+- `src/main.rs` — tokio entrypoint, parses args, dispatches transport.
+- `src/server.rs` — builds the rmcp service with tools + prompts.
+- `src/cli.rs` — clap arg parser + Transport enum + --list-tools.
+- `src/transports/{stdio,sse,http}.rs` — one runner per transport.
+- `src/tools/`, `src/prompts/` — pure functions, unit-tested.
+
+## CLI inventory
+
+`cargo run -- --json --list-tools` prints the tool registry as JSON (M-03).
+
+## Note on beta status
+
+`rmcp` is the official Rust MCP SDK but its API is pre-1.0. If a `cargo build`
+fails after a dependency update, pin `rmcp` to a known-good version in Cargo.toml.
+
+## DARE skills
+
+See `.dare/skills.yml`.

package/templates/stacks/mcp-rust/openapi.json.tera

@@ -0,0 +1,31 @@
+{
+  "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-rust/src/cli.rs.tera

@@ -0,0 +1,33 @@
+//! CLI argument parsing — transport selection + tool inventory.
+use clap::{Parser, ValueEnum};
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum Transport {
+    Stdio,
+    Sse,
+    Http,
+}
+
+#[derive(Debug, Parser)]
+#[command(name = "{{ projectName }}", version, about = "DARE-shaped MCP server")]
+pub struct Cli {
+    /// Transport to serve on. Overridden by MCP_TRANSPORT env if that is set.
+    #[arg(long, value_enum, default_value = "{{ defaultTransport }}", env = "MCP_TRANSPORT")]
+    pub transport: Transport,
+
+    /// Bind host for sse/http transports.
+    #[arg(long, default_value = "0.0.0.0", env = "MCP_HOST")]
+    pub host: String,
+
+    /// Bind port for sse/http transports.
+    #[arg(long, default_value_t = 3001, env = "MCP_PORT")]
+    pub port: u16,
+
+    /// Emit machine-readable JSON (use with --list-tools).
+    #[arg(long)]
+    pub json: bool,
+
+    /// List registered tools as JSON and exit (M-03).
+    #[arg(long)]
+    pub list_tools: bool,
+}