@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/stacks/mcp-go/internal/server/server.go.tpl

@@ -0,0 +1,80 @@
+// Package server builds the mcp-go server with tools and prompts.
+//
+// NOTE: mark3labs/mcp-go is pre-1.0. The registration calls below match the
+// v0.8.x surface; adjust here if an upstream bump changes the API. Business
+// logic lives in internal/tools and internal/prompts (pure, unit-tested) so a
+// breaking SDK change only touches this file.
+package server
+
+import (
+	"context"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+
+	"{{moduleName}}/internal/prompts"
+	"{{moduleName}}/internal/tools"
+)
+
+// New builds and returns a configured MCP server.
+func New() *server.MCPServer {
+	s := server.NewMCPServer(
+		"{{projectName}}",
+		"0.1.0",
+		server.WithToolCapabilities(true),
+		server.WithPromptCapabilities(true),
+	)
+
+	echoTool := mcp.NewTool("echo",
+		mcp.WithDescription("Returns its input. Canonical smoke test for an MCP server."),
+		mcp.WithString("text",
+			mcp.Required(),
+			mcp.Description("Text to echo back"),
+		),
+	)
+	s.AddTool(echoTool, func(_ context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		// v0.54: tool arguments are accessed via GetArguments() (returns map[string]any).
+		text, _ := req.GetArguments()["text"].(string)
+		out, err := tools.Echo(text)
+		if err != nil {
+			return mcp.NewToolResultError(err.Error()), nil
+		}
+		return mcp.NewToolResultText(out), nil
+	})
+
+	summarizePrompt := mcp.NewPrompt("summarize",
+		mcp.WithPromptDescription("Summarize the given text in 1-2 sentences."),
+		mcp.WithArgument("text", mcp.ArgumentDescription("Text to summarize"), mcp.RequiredArgument()),
+	)
+	s.AddPrompt(summarizePrompt, func(_ context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+		text := req.Params.Arguments["text"]
+		body := prompts.Summarize(text)
+		return mcp.NewGetPromptResult(
+			"summarize",
+			[]mcp.PromptMessage{
+				mcp.NewPromptMessage(mcp.RoleUser, mcp.NewTextContent(body)),
+			},
+		), nil
+	})
+
+	return s
+}
+
+// InventoryJSON returns a machine-readable tool inventory for --list-tools (M-03).
+func InventoryJSON() map[string]any {
+	return map[string]any{
+		"tools": []map[string]any{
+			{
+				"name":        "echo",
+				"description": "Returns its input. Canonical smoke test for an MCP server.",
+				"inputSchema": map[string]any{
+					"type":     "object",
+					"required": []string{"text"},
+					"properties": map[string]any{
+						"text": map[string]any{"type": "string", "minLength": 1},
+					},
+				},
+			},
+		},
+	}
+}

package/templates/stacks/mcp-go/internal/tools/echo.go

@@ -0,0 +1,15 @@
+// Package tools holds pure tool implementations, testable without the SDK.
+package tools
+
+import "errors"
+
+// ErrEmpty is returned when echo is given an empty string.
+var ErrEmpty = errors.New("text must be a non-empty string")
+
+// Echo returns its input verbatim.
+func Echo(text string) (string, error) {
+	if text == "" {
+		return "", ErrEmpty
+	}
+	return text, nil
+}

package/templates/stacks/mcp-go/internal/transports/http.go.tpl

@@ -0,0 +1,21 @@
+package transports
+
+import (
+	"fmt"
+
+	mcpserver "github.com/mark3labs/mcp-go/server"
+
+	srv "{{moduleName}}/internal/server"
+)
+
+// RunHTTP serves the MCP server over Streamable HTTP.
+//
+// NOTE: the streamable-http constructor name may vary across mark3labs/mcp-go
+// releases. If `go build` fails after an SDK bump, check the server package
+// for the current streamable HTTP server type.
+func RunHTTP(host, port string) error {
+	s := srv.New()
+	addr := fmt.Sprintf("%s:%s", host, port)
+	httpServer := mcpserver.NewStreamableHTTPServer(s)
+	return httpServer.Start(addr)
+}

package/templates/stacks/mcp-go/internal/transports/sse.go.tpl

@@ -0,0 +1,17 @@
+package transports
+
+import (
+	"fmt"
+
+	mcpserver "github.com/mark3labs/mcp-go/server"
+
+	srv "{{moduleName}}/internal/server"
+)
+
+// RunSSE serves the MCP server over SSE-over-HTTP.
+func RunSSE(host, port string) error {
+	s := srv.New()
+	addr := fmt.Sprintf("%s:%s", host, port)
+	sse := mcpserver.NewSSEServer(s)
+	return sse.Start(addr)
+}

package/templates/stacks/mcp-go/internal/transports/stdio.go.tpl

@@ -0,0 +1,14 @@
+// Package transports — one runner per MCP transport.
+package transports
+
+import (
+	mcpserver "github.com/mark3labs/mcp-go/server"
+
+	srv "{{moduleName}}/internal/server"
+)
+
+// RunStdio serves over stdin/stdout — the default for local agents.
+func RunStdio() error {
+	s := srv.New()
+	return mcpserver.ServeStdio(s)
+}

package/templates/stacks/mcp-go/llms.txt.tpl

@@ -0,0 +1,60 @@
+# {{projectName}}
+
+DARE-shaped MCP server (Go, mark3labs/mcp-go). Default transport: **{{defaultTransport}}**. BETA.
+
+## Setup
+
+```bash
+cp .env.example .env
+go mod tidy
+go run ./cmd/server
+```
+
+## Commands
+
+- `go run ./cmd/server` — start server (transport via --transport or MCP_TRANSPORT env)
+- `go test ./...` — tests
+- `golangci-lint run` — lint
+- `govulncheck ./...` — vuln scan
+- `npx @modelcontextprotocol/inspector go run ./cmd/server` — MCP Inspector
+
+## Tools (registered in internal/server/server.go)
+
+| 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).
+- `http` — Streamable HTTP on MCP_PORT (default 3001).
+
+## Architecture
+
+- `cmd/server/main.go` — entrypoint, flag parsing, transport dispatch.
+- `internal/server/server.go` — builds the mcp-go server with tools + prompts.
+- `internal/tools/`, `internal/prompts/` — pure functions, unit-tested.
+- `internal/transports/` — one runner per transport.
+
+## CLI inventory
+
+`go run ./cmd/server --json --list-tools` prints the tool registry as JSON (M-03).
+
+## Note on beta status
+
+`mark3labs/mcp-go` is community-led. If Anthropic ships an official Go SDK,
+migrate `internal/server` + `internal/transports` to it; the pure
+tools/prompts functions stay unchanged.
+
+## DARE skills
+
+See `.dare/skills.yml`.

package/templates/stacks/mcp-go/openapi.json.tpl

@@ -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-go/tests/echo_test.go.tpl

@@ -0,0 +1,37 @@
+// Smoke tests — pure tools/prompts, no SDK or transport needed.
+package tests
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"{{moduleName}}/internal/prompts"
+	"{{moduleName}}/internal/server"
+	"{{moduleName}}/internal/tools"
+)
+
+func TestEchoReturnsInput(t *testing.T) {
+	out, err := tools.Echo("hello")
+	require.NoError(t, err)
+	require.Equal(t, "hello", out)
+}
+
+func TestEchoRejectsEmpty(t *testing.T) {
+	_, err := tools.Echo("")
+	require.ErrorIs(t, err, tools.ErrEmpty)
+}
+
+func TestSummarizeIncludesInput(t *testing.T) {
+	out := prompts.Summarize("long text here")
+	require.Contains(t, out, "long text here")
+	require.Contains(t, out, "Summarize")
+}
+
+func TestInventoryListsEcho(t *testing.T) {
+	inv := server.InventoryJSON()
+	toolsList, ok := inv["tools"].([]map[string]any)
+	require.True(t, ok)
+	require.NotEmpty(t, toolsList)
+	require.Equal(t, "echo", toolsList[0]["name"])
+}

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

@@ -0,0 +1,16 @@
+# MCP transport — overrides --transport flag if set
+# Valid: stdio | sse | http
+MCP_TRANSPORT=stdio
+
+# HTTP/SSE transport port (ignored on stdio)
+MCP_PORT=3001
+
+# Rate limit (HTTP/SSE only — stdio is single-client local)
+RATE_LIMIT_RPM=120
+
+# Logging
+LOG_LEVEL=info
+
+# LLM provider (optional — for tools that call out)
+LLM_PROVIDER=dummy
+# OPENAI_API_KEY=

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

@@ -0,0 +1,54 @@
+name: DARE CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  audit:
+    name: Audit dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm audit --audit-level=high
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm test

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}`);
+}