@musashishao/agent-kit 1.0.0 → 1.0.1

package/.agent/skills/mcp-builder/typescript-template.md

@@ -0,0 +1,361 @@
+# TypeScript MCP Server Template
+
+> Copy this template to quickly start a new MCP server.
+
+## Project Structure
+
+```
+my-mcp-server/
+├── src/
+│   ├── index.ts          # Entry point
+│   ├── tools/            # Tool implementations
+│   │   ├── index.ts
+│   │   └── example.ts
+│   ├── resources/        # Resource handlers
+│   │   └── index.ts
+│   └── utils/            # Utilities
+│       └── index.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Files
+
+### package.json
+
+```json
+{
+  "name": "my-mcp-server",
+  "version": "1.0.0",
+  "description": "My MCP Server",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "my-mcp-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0",
+    "eslint": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### src/index.ts
+
+```typescript
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { registerTools } from "./tools/index.js";
+import { registerResources } from "./resources/index.js";
+
+// Configuration
+const SERVER_NAME = "my-mcp-server";
+const SERVER_VERSION = "1.0.0";
+
+// Create server instance
+const server = new McpServer({
+  name: SERVER_NAME,
+  version: SERVER_VERSION,
+});
+
+// Register tools and resources
+registerTools(server);
+registerResources(server);
+
+// Error handling
+process.on("uncaughtException", (error) => {
+  console.error("Uncaught exception:", error);
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  console.error("Unhandled rejection:", reason);
+  process.exit(1);
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  
+  await server.connect(transport);
+  
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+}
+
+main().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});
+```
+
+### src/tools/index.ts
+
+```typescript
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function registerTools(server: McpServer) {
+  // Example: Greet tool
+  server.tool(
+    "greet",
+    "Greet a user by name",
+    {
+      name: z.string().describe("The name of the user to greet"),
+      language: z.enum(["en", "es", "fr"]).default("en").describe("Language for greeting"),
+    },
+    async ({ name, language }) => {
+      const greetings = {
+        en: `Hello, ${name}!`,
+        es: `¡Hola, ${name}!`,
+        fr: `Bonjour, ${name}!`,
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: greetings[language],
+          },
+        ],
+      };
+    }
+  );
+
+  // Example: Calculate tool
+  server.tool(
+    "calculate",
+    "Perform a mathematical calculation",
+    {
+      operation: z.enum(["add", "subtract", "multiply", "divide"]).describe("The operation to perform"),
+      a: z.number().describe("First number"),
+      b: z.number().describe("Second number"),
+    },
+    async ({ operation, a, b }) => {
+      let result: number;
+
+      switch (operation) {
+        case "add":
+          result = a + b;
+          break;
+        case "subtract":
+          result = a - b;
+          break;
+        case "multiply":
+          result = a * b;
+          break;
+        case "divide":
+          if (b === 0) {
+            return {
+              content: [{ type: "text", text: "Error: Division by zero" }],
+              isError: true,
+            };
+          }
+          result = a / b;
+          break;
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ operation, a, b, result }),
+          },
+        ],
+      };
+    }
+  );
+
+  // Add more tools here...
+}
+```
+
+### src/resources/index.ts
+
+```typescript
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export function registerResources(server: McpServer) {
+  // Example: Status resource
+  server.resource(
+    "status",
+    "status://server",
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            status: "running",
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime(),
+          }),
+        },
+      ],
+    })
+  );
+
+  // Example: Config resource
+  server.resource(
+    "config",
+    "config://settings",
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            version: "1.0.0",
+            features: ["tools", "resources"],
+            environment: process.env.NODE_ENV || "development",
+          }),
+        },
+      ],
+    })
+  );
+
+  // Add more resources here...
+}
+```
+
+### src/utils/index.ts
+
+```typescript
+/**
+ * Generate a unique ID
+ */
+export function generateId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Validate environment variable
+ */
+export function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+/**
+ * Optional environment variable with default
+ */
+export function getEnv(name: string, defaultValue: string): string {
+  return process.env[name] || defaultValue;
+}
+
+/**
+ * Safe JSON parse with fallback
+ */
+export function safeJsonParse<T>(json: string, fallback: T): T {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Delay utility
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+```
+
+## Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/path/to/my-mcp-server/dist/index.js"],
+      "env": {
+        "MY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Development mode (auto-reload)
+npm run dev
+
+# Build for production
+npm run build
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector node dist/index.js
+
+# Run production
+npm start
+```
+
+## Publishing to npm
+
+```bash
+# 1. Update version
+npm version patch  # or minor, major
+
+# 2. Build
+npm run build
+
+# 3. Publish
+npm publish --access public
+
+# Users can then run:
+npx your-package-name
+```