@cyanheads/mcp-ts-core 0.1.0-beta.12

package/templates/biome.template.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100,
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always",
+      "arrowParentheses": "always",
+      "bracketSpacing": true
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedVariables": "error",
+        "noUnusedFunctionParameters": "error",
+        "noUnusedImports": "error"
+      },
+      "style": {
+        "useConst": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "warn",
+        "noVar": "error",
+        "useAwait": "warn"
+      }
+    }
+  }
+}

package/templates/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "devcheck": "biome check . && tsc --noEmit",
+    "format": "biome check --fix .",
+    "test": "vitest run",
+    "dev:stdio": "tsx src/index.ts",
+    "dev:http": "MCP_TRANSPORT_TYPE=http tsx src/index.ts",
+    "start:stdio": "node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.1.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "tsc-alias": "^1.8.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}

package/templates/src/index.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview {{SERVER_NAME}} MCP server entry point.
+ * @module index
+ */
+
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { echoTool } from './mcp-server/tools/definitions/echo.tool.js';
+import { echoResource } from './mcp-server/resources/definitions/echo.resource.js';
+import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
+
+await createApp({
+  tools: [echoTool],
+  resources: [echoResource],
+  prompts: [echoPrompt],
+});

package/templates/src/mcp-server/prompts/definitions/echo.prompt.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Echo prompt — a minimal starting point for building MCP prompts.
+ * @module mcp-server/prompts/definitions/echo.prompt
+ */
+
+import { z } from 'zod';
+import { prompt } from '@cyanheads/mcp-ts-core';
+
+// Prompts are pure message templates — no Context, no auth, no side effects.
+// They generate conversation messages that clients can use to start interactions.
+export const echoPrompt = prompt('template_echo_message', {
+  description: 'Generates a simple echo message. Replace this with your first real prompt.',
+  args: z.object({
+    message: z.string().describe('The message to echo.'),
+  }),
+  generate: (args) => [
+    { role: 'user', content: { type: 'text', text: `Echo: ${args.message}` } },
+  ],
+});

package/templates/src/mcp-server/resources/definitions/echo.resource.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Echo resource — a minimal starting point for building MCP resources.
+ * @module mcp-server/resources/definitions/echo.resource
+ */
+
+import { z } from 'zod';
+import { resource } from '@cyanheads/mcp-ts-core';
+
+// Resource URI templates use RFC 6570 syntax. Params are extracted from {placeholders}.
+// Like tools, prefix names with your server name: template-echo, tasks-status, etc.
+export const echoResource = resource('echo://{message}', {
+  name: 'template-echo-resource',
+  description: 'Echoes a message from the URI. Replace this with your first real resource.', // Descriptions help the LLM decide when to read this resource.
+  mimeType: 'application/json',
+  params: z.object({
+    message: z.string().describe('The message to echo back.'),
+  }),
+  output: z.object({
+    message: z.string().describe('The echoed message.'),
+  }),
+
+  handler(params, ctx) {
+    ctx.log.info('Echoing resource', { message: params.message });
+    return { message: params.message };
+  },
+
+  list: () => ({
+    resources: [{ uri: 'echo://hello', name: 'Echo Hello' }], // Static discovery — clients call list to find available resources.
+  }),
+});

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Echo tool — a minimal starting point for building MCP tools.
+ * @module mcp-server/tools/definitions/echo.tool
+ */
+
+import { z } from 'zod';
+import { tool } from '@cyanheads/mcp-ts-core';
+
+// Tool names are snake_case, prefixed with your server name to avoid collisions across servers. e.g. for a "tasks" server: tasks_fetch_list, tasks_create_item.
+export const echoTool = tool('template_echo_message', {
+  description: 'Echoes a message back. Replace this with your first real tool.', // Descriptions are what the LLM reads to decide when to call the tool.
+  annotations: { readOnlyHint: true },
+  input: z.object({
+    message: z.string().describe('The message to echo back.'),
+  }),
+  output: z.object({
+    message: z.string().describe('The echoed message.'),
+  }), // All Zod fields need .describe() — that's LLM context too.
+
+  handler(input, ctx) {
+    ctx.log.info('Echoing message', { message: input.message });
+    return { message: input.message }; // Handlers are pure: throw McpError on failure, no try/catch.
+  },
+});

package/templates/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: { '@/': new URL('./src/', import.meta.url).pathname },
+  },
+  test: {
+    globals: false,
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
+  },
+});

package/tsconfig.base.json

@@ -0,0 +1,44 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+
+    "importHelpers": true,
+    "incremental": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "lib": ["ESNext"],
+    "types": ["node"],
+
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "resolveJsonModule": true,
+    "allowJs": false,
+
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/vitest.config.base.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Base Vitest configuration for consumer servers.
+ * Extend this in your server's `vitest.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig, mergeConfig } from 'vitest/config';
+ * import coreConfig from '@cyanheads/mcp-ts-core/vitest.config';
+ *
+ * export default mergeConfig(coreConfig, defineConfig({
+ *   resolve: {
+ *     alias: { '@/': new URL('./src/', import.meta.url).pathname },
+ *   },
+ * }));
+ * ```
+ *
+ * @module vitest.config.base
+ */
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  ssr: {
+    noExternal: ['zod'],
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    pool: 'forks',
+    isolate: true,
+    coverage: {
+      provider: 'istanbul',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.d.ts'],
+    },
+  },
+});