Initial commit

skills/mcp-server-creator/workflow/phase-1-discovery.md

@@ -0,0 +1,37 @@
+# Phase 1: Discovery & Language Selection
+
+**Purpose**: Understand what the user wants to build and choose the right SDK
+
+## Questions to Ask
+
+### 1. Server Purpose
+- "What data source, tools, or workflows do you want to expose to AI?"
+- Examples: "Access PostgreSQL database", "Search Jira tickets", "Format code"
+
+### 2. Target AI Application
+- Claude Desktop (most common)
+- Custom AI application
+- Multiple clients
+
+### 3. Programming Language Preference
+- **TypeScript/Node.js** (recommended for web APIs, JavaScript ecosystem)
+- **Python** (recommended for data processing, ML workflows)
+- **Java/Spring AI** (enterprise Java applications)
+- **Kotlin** (Android/JVM applications)
+- **C#/.NET** (Windows/Azure applications)
+
+### 4. Capability Types Needed
+- **Tools**: Functions AI can call (e.g., "get_weather", "search_database")
+- **Resources**: Data AI can read (e.g., file contents, API responses)
+- **Prompts**: Specialized templates for common tasks
+
+## Output
+
+Clear understanding of:
+- Server purpose
+- Language choice
+- Capabilities needed (tools/resources/prompts)
+
+## Transition
+
+Proceed to Phase 2 (Project Structure Generation)

skills/mcp-server-creator/workflow/phase-2-structure.md

@@ -0,0 +1,88 @@
+# Phase 2: Project Structure Generation
+
+**Purpose**: Create proper project structure with SDK integration
+
+## TypeScript Project Setup
+
+```bash
+# Create project directory
+mkdir mcp-[server-name]
+cd mcp-[server-name]
+
+# Initialize npm project
+npm init -y
+
+# Install dependencies
+npm install @modelcontextprotocol/sdk zod
+npm install -D @types/node typescript
+```
+
+### TypeScript Configuration (tsconfig.json)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+### Package.json Scripts
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "watch": "tsc --watch",
+    "start": "node build/index.js"
+  }
+}
+```
+
+## Python Project Setup
+
+```bash
+# Create project with uv
+uv init mcp-[server-name]
+cd mcp-[server-name]
+
+# Set up virtual environment
+uv venv
+source .venv/bin/activate
+
+# Install MCP SDK
+uv add "mcp[cli]"
+```
+
+## File Structure
+
+```
+mcp-server-name/
+├── src/
+│   └── index.ts (or main.py)
+├── build/ (TypeScript only)
+├── .env.example
+├── .gitignore
+├── package.json / pyproject.toml
+├── tsconfig.json (TypeScript only)
+└── README.md
+```
+
+## Output
+
+Complete project structure with dependencies installed
+
+## Transition
+
+Proceed to Phase 3 (Server Implementation)

skills/mcp-server-creator/workflow/phase-3-implementation.md

@@ -0,0 +1,134 @@
+# Phase 3: Server Implementation
+
+**Purpose**: Generate core server code with requested capabilities
+
+## TypeScript Server Template
+
+```typescript
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Initialize server
+const server = new Server(
+  {
+    name: "server-name",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+    },
+  }
+);
+
+// Example Tool
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "tool_name",
+      description: "What this tool does",
+      inputSchema: {
+        type: "object",
+        properties: {
+          param: { type: "string", description: "Parameter description" }
+        },
+        required: ["param"]
+      }
+    }
+  ]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "tool_name") {
+    const { param } = request.params.arguments;
+    const result = await performOperation(param);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  }
+
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+// Start server with STDIO transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // CRITICAL: Never console.log() in STDIO mode!
+  console.error("Server running on stdio");
+}
+
+main().catch(console.error);
+```
+
+## Python Server Template (FastMCP)
+
+```python
+#!/usr/bin/env python3
+
+from mcp.server.fastmcp import FastMCP
+import os
+
+# Initialize server
+mcp = FastMCP("server-name")
+
+@mcp.tool()
+async def tool_name(param: str) -> str:
+    """
+    Description of what this tool does.
+
+    Args:
+        param: Parameter description
+
+    Returns:
+        Result description
+    """
+    result = await perform_operation(param)
+    return str(result)
+
+@mcp.resource("resource://template/{id}")
+async def get_resource(id: str) -> str:
+    """Get resource by ID."""
+    return f"Resource content for {id}"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Key Implementation Patterns
+
+### 1. Tool Definition
+- Clear, descriptive names
+- Comprehensive descriptions (AI uses this!)
+- Strong typing with Zod/type hints
+- Proper error handling
+
+### 2. Resource Patterns
+- URI templates for dynamic resources
+- Efficient data fetching (avoid heavy computation)
+- Proper MIME types
+
+### 3. Logging Rules
+- **STDIO servers**: NEVER use console.log/print (corrupts JSON-RPC)
+- Use console.error / logging.error (stderr is safe)
+- **HTTP servers**: stdout is safe
+
+## Output
+
+Fully implemented server with requested capabilities
+
+## Transition
+
+Proceed to Phase 4 (Environment & Security)

skills/mcp-server-creator/workflow/phase-4-security.md

@@ -0,0 +1,61 @@
+# Phase 4: Environment & Security
+
+**Purpose**: Secure secrets and configure environment
+
+## Generate .env.example
+
+```bash
+# API Keys and Secrets
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+
+# Server Configuration
+PORT=3000
+LOG_LEVEL=info
+```
+
+## Generate .gitignore
+
+```
+# Dependencies
+node_modules/
+.venv/
+__pycache__/
+
+# Build outputs
+build/
+dist/
+*.pyc
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+## Security Best Practices
+
+- ✓ Never commit .env files
+- ✓ Use environment variables for all secrets
+- ✓ Validate all inputs with schemas
+- ✓ Implement proper error handling (don't leak internals)
+- ✓ Use HTTPS for HTTP transport servers
+
+## Output
+
+Secure configuration with secrets management
+
+## Transition
+
+Proceed to Phase 5 (Claude Desktop Integration)

skills/mcp-server-creator/workflow/phase-5-integration.md

@@ -0,0 +1,60 @@
+# Phase 5: Claude Desktop Integration
+
+**Purpose**: Configure server in Claude Desktop for immediate use
+
+## Configuration Location
+
+- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+## TypeScript Configuration
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server-name/build/index.js"],
+      "env": {
+        "API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Python Configuration
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/mcp-server-name",
+        "run",
+        "main.py"
+      ],
+      "env": {
+        "API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Critical Requirements
+
+- ✅ **Use ABSOLUTE paths** (not relative like `./` or `~/`)
+- ✅ Run `npm run build` before testing (TypeScript)
+- ✅ Completely restart Claude Desktop (Cmd+Q on macOS)
+- ✅ Valid JSON syntax (check with `python -m json.tool`)
+
+## Output
+
+Complete Claude Desktop configuration with restart instructions
+
+## Transition
+
+Proceed to Phase 6 (Testing & Validation)

skills/mcp-server-creator/workflow/phase-6-testing.md

@@ -0,0 +1,60 @@
+# Phase 6: Testing & Validation
+
+**Purpose**: Verify server works correctly before deployment
+
+## Testing Workflow
+
+### 1. Build Check (TypeScript)
+
+```bash
+npm run build
+# Should complete without errors
+# Verify build/index.js exists
+```
+
+### 2. MCP Inspector Testing
+
+```bash
+# Install MCP Inspector
+npx @modelcontextprotocol/inspector node build/index.js
+
+# Or for Python
+npx @modelcontextprotocol/inspector uv run main.py
+```
+
+- Opens browser interface to test tools/resources
+- Validates schemas and responses
+- Great for debugging before Claude integration
+
+### 3. Claude Desktop Integration Test
+
+- Add to claude_desktop_config.json
+- Completely restart Claude Desktop
+- Check logs: `~/Library/Logs/Claude/mcp*.log`
+- Look for server in "🔌" (attachments) menu
+
+### 4. Functional Testing in Claude
+
+Test with natural language queries:
+- "Use [server-name] to [perform action]"
+- "Can you [tool description]?"
+- Verify tool appears in suggestions
+- Check response accuracy
+
+## Debugging Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Server not detected | Invalid path | Use absolute path, verify file exists |
+| Tools don't appear | Build not run | Run `npm run build` |
+| "Server error" | stdout logging | Remove console.log, use console.error |
+| Connection timeout | Server crash | Check mcp-server-NAME.log for errors |
+| Invalid config | JSON syntax | Validate JSON, check quotes/commas |
+
+## Output
+
+Validated, working MCP server with test results
+
+## Transition
+
+Proceed to Phase 7 (Documentation & Handoff)

skills/mcp-server-creator/workflow/phase-7-documentation.md

@@ -0,0 +1,97 @@
+# Phase 7: Documentation & Handoff
+
+**Purpose**: Provide user with complete documentation and next steps
+
+## Generate README.md
+
+```markdown
+# MCP Server: [Name]
+
+## Description
+[What this server does and why it's useful]
+
+## Capabilities
+
+### Tools
+- **tool_name**: Description of what it does
+  - Parameters: param1 (type) - description
+  - Returns: description
+
+### Resources
+- **resource://pattern/{id}**: Description
+
+### Prompts
+- **prompt_name**: Description
+
+## Setup
+
+### Prerequisites
+- Node.js 18+ / Python 3.10+
+- Claude Desktop or MCP-compatible client
+
+### Installation
+
+1. Clone/download this server
+2. Install dependencies:
+   ```bash
+   npm install && npm run build
+   # OR
+   uv sync
+   ```
+
+3. Configure environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your credentials
+   ```
+
+4. Add to Claude Desktop config (see Phase 5)
+
+5. Restart Claude Desktop completely
+
+## Usage Examples
+
+### Example 1: [Use Case]
+Query: "[Natural language query]"
+Expected: [What happens]
+
+## Development
+
+### Running Locally
+```bash
+npm run watch  # Auto-rebuild on changes
+```
+
+### Testing with MCP Inspector
+```bash
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+### Debugging
+Logs location: `~/Library/Logs/Claude/mcp-server-[name].log`
+
+## Security Notes
+- Never commit .env file
+- Rotate API keys regularly
+- Validate all inputs
+```
+
+## Provide Next Steps
+
+```markdown
+## Next Steps
+
+1. ✅ Server code generated at: [path]
+2. ⬜ Review and customize tool implementations
+3. ⬜ Add your API keys to .env
+4. ⬜ Run build: `npm run build` or test with `uv run`
+5. ⬜ Test with MCP Inspector
+6. ⬜ Add to Claude Desktop config
+7. ⬜ Restart Claude Desktop
+8. ⬜ Test with natural language queries
+9. ⬜ Iterate and enhance based on usage
+```
+
+## Output
+
+Complete documentation and clear path to production use