@myatkyawthu/mcp-connect 0.1.1 → 0.2.0

package/README.md

@@ -5,304 +5,166 @@
 [![npm version](https://badge.fury.io/js/mcp-connect.svg)](https://www.npmjs.com/package/mcp-connect)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Quick Start
+## 🚀 Claude Desktop Setup (5 Minutes)
 
-### Option 1: Global Installation (Recommended)
+### Step 1: Install mcp-connect
 
 ```bash
-# Install globally with npm
-npm install -g mcp-connect
+npm install -g @myatkyawthu/mcp-connect
 ```
+### Step 2: Create mcp.config.js
 
-Create `mcp.config.js` in your project:
-
-```javascript
-import { defineMCP } from "mcp-connect"
-
-export default defineMCP({
-  name: "My App",
-  version: "1.0.0",
-  tools: [
-    ["hello", async ({ name }) => `Hello ${name}!`],
-    ["getTodos", async () => [{ id: 1, title: "Buy milk" }]],
-  ]
-})
-```
-
-Start the server from your project directory:
+### Step 2: Create Your MCP Server
 
 ```bash
-mcp-connect
-```
-
-### Option 2: Local Installation
+# Navigate to your project directory
+cd your-project
 
-```bash
-# Install locally with npm
-npm install mcp-connect
+# Generate sample config
+mcp-connect init
 ```
 
-Start with npx:
-
-```bash
-npx mcp-connect
-```
-
-Connect your AI agent via STDIO transport (Claude Desktop)!
-
-## 🎯 Features
-
-- **Zero Config** - Works out of the box with minimal setup
-- **MCP Compliant** - Uses official MCP SDK with JSON-RPC 2.0
-- **STDIO Transport** - Direct communication with Claude Desktop and other MCP clients
-- **Pure JavaScript** - No compilation needed, runs directly on Node.js 18+
-- **Production Ready** - Enterprise-grade error handling and logging
-- **Performance Monitoring** - Built-in execution timing and debugging
-- **Universal** - Works with npm, pnpm, and yarn
-- **Claude Desktop Ready** - Works seamlessly with Claude Desktop and other MCP clients
-- **Simple API** - Clean, declarative tool definitions with flexible formats
-
-## 📖 Documentation
-
-### Tool Definition Formats
+This creates `mcp.config.js` with example tools:
 
 ```javascript
-// Tuple format (simple)
-["toolName", async (args) => result]
-
-// Object format (with metadata)
-{
-  name: "toolName",
-  description: "What this tool does",
-  handler: async (args) => result,
-  schema: { /* JSON schema for input validation */ }
-}
-```
-
-### Configuration Options
+import { defineMCP } from "@myatkyawthu/mcp-connect";
 
-```javascript
-defineMCP({
-  name: "My MCP Server",      // Required: Server name
-  version: "1.0.0",           // Required: Server version
-  description: "My server",   // Optional: Description
+export default defineMCP({
+  name: "My MCP App",
+  version: "1.0.0",
   tools: [
-    // Your tool definitions
+    ["hello", async ({ name = "World" }) => `Hello ${name}!`],
+    ["echo", async ({ message }) => `Echo: ${message}`]
   ]
-})
-```
-
-## 🔧 CLI Usage
-
-### Global Installation
-
-```bash
-# Start server (looks for mcp.config.ts in current directory)
-mcp-connect
-
-# With debug logging and performance tracking
-MCP_DEBUG=1 mcp-connect
-
-# Performance tracking only
-MCP_PERF=1 mcp-connect
-
-# Custom log level
-MCP_LOG_LEVEL=warn mcp-connect
-```
-
-### Local Installation
-
-```bash
-# Using npx
-npx mcp-connect
-
-# With environment variables
-MCP_DEBUG=1 npx mcp-connect
-```
-
-## 🔍 Logging & Debugging
-
-MCP-Connect includes comprehensive logging and debugging features:
-
-### Environment Variables
-
-- `MCP_DEBUG=1` - Enable debug logging with full MCP message tracing
-- `MCP_PERF=1` - Enable performance tracking for tool execution times
-- `MCP_LOG_LEVEL=level` - Set minimum log level (debug, info, warn, error)
-
-### Log Output Examples
-
-```
-[MCP-INFO] 2024-01-15T10:30:45.123Z MCP server "Todo App" started (stdio, 3 tools)
-[MCP-DEBUG] 2024-01-15T10:30:46.456Z Tool execution started: addTodo [req:abc123]
-[MCP-INFO] 2024-01-15T10:30:46.478Z Tool execution completed: addTodo (22ms) [req:abc123]
-```
-
-## ✅ Configuration Validation
-
-MCP-Connect provides comprehensive configuration validation with helpful error messages:
-
-```
-❌ Configuration Errors:
-  1. tools[0].name: Tool name must be a non-empty string
-     Current value: ""
-     Suggestion: "myToolName"
-
-⚠️  Configuration Warnings:
-  1. version: Version doesn't follow semantic versioning
-     Suggestion: Use format: "1.0.0"
+});
 ```
+### Step 3: Test Locally
 
-## 🛡️ Error Handling
-
-- **Tool Execution Timeouts** - 30-second default timeout prevents hanging
-- **Graceful Shutdown** - Proper cleanup on SIGINT/SIGTERM
-- **Sanitized Errors** - Safe error messages without sensitive information
-- **MCP-Compliant Errors** - Proper JSON-RPC error format
-
-## 🤝 AI Agent Integration
-
-### Claude Desktop
+### Step 3: Configure Claude Desktop
 
-#### Global Installation (Recommended)
+Open Claude Desktop config file:
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add your MCP server:
 
 ```json
 {
   "mcpServers": {
     "my-app": {
       "command": "mcp-connect",
-      "cwd": "/path/to/your/project"
+      "args": ["C:/full/path/to/your/mcp.config.js"]
     }
   }
 }
 ```
 
-#### Local Installation
+**Important**: Use the full absolute path to your `mcp.config.js` file.
 
-```json
-{
-  "mcpServers": {
-    "my-app": {
-      "command": "npx",
-      "args": ["mcp-connect"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
+### Step 4: Start & Test
 
-#### Alternative: Package Script
+1. **Restart Claude Desktop** completely
+2. **Test connection**: Ask Claude *"What tools do you have available?"*
+3. **Use your tools**: Try *"Hello there!"* or *"Echo this message"*
 
-Add to your project's `package.json`:
+✅ **Done!** Your functions are now available to Claude Desktop.
 
-```json
-{
-  "scripts": {
-    "mcp": "mcp-connect"
-  }
-}
+---
+
+## 📖 Tool Definition Guide
+
+### Simple Format (Recommended)
+
+```javascript
+// Just name and function
+["toolName", async (args) => "result"]
 ```
+## 🔧 CLI Usage
 
-Then in Claude Desktop config:
+### Advanced Format (With Validation)
 
-```json
+```javascript
 {
-  "mcpServers": {
-    "my-app": {
-      "command": "npm",
-      "args": ["run", "mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
+  name: "toolName",
+  description: "What this tool does",
+  schema: {
+    type: "object",
+    properties: {
+      param: { type: "string", description: "Parameter description" }
+    },
+    required: ["param"]
+  },
+  handler: async ({ param }) => `Result: ${param}`
 }
 ```
 
-### Other MCP Clients
-
-Any MCP-compliant client can connect using the STDIO transport. The server implements the full MCP specification with:
+## 🛠 Development Commands
 
-- `tools/list` - List available tools
-- `tools/call` - Execute tool functions
-- Proper JSON-RPC 2.0 messaging
-- Standard MCP lifecycle management
+```bash
+# Start with auto-reload during development
+npm run dev
 
-## 📁 Examples
+# Start server with specific config file
+mcp-connect /path/to/your/mcp.config.js
 
-### Todo App Example
+# Format code
+npm run format
 
-```javascript
-import { defineMCP } from "mcp-connect";
+# Lint code
+npm run lint
+```
 
-const todos = [{ id: 1, title: "Buy milk", completed: false }];
+## 🔧 Troubleshooting
 
-export default defineMCP({
-  name: "Todo App",
-  version: "1.0.0",
-  description: "Simple todo list management via MCP",
-  tools: [
-    // Simple tuple format
-    ["getTodos", async () => todos],
-    
-    // Object format with schema validation
-    {
-      name: "addTodo",
-      description: "Add a new todo item",
-      schema: {
-        type: "object",
-        properties: {
-          title: { type: "string", description: "Todo title" }
-        },
-        required: ["title"]
-      },
-      handler: async ({ title }) => {
-        const newTodo = { id: Date.now(), title, completed: false };
-        todos.push(newTodo);
-        return newTodo;
-      }
-    }
-  ]
-});
+### Config File Not Found
+```bash
+# Create sample config
+mcp-connect init
 ```
 
-Check out the [examples](./examples) directory for complete working examples.
+### Claude Desktop Not Connecting
+1. Check config file path is absolute
+2. Restart Claude Desktop completely
+3. Check Claude Desktop logs for errors
 
-## 🛠 Development
+### Tool Not Working
+1. Verify tool syntax in `mcp.config.js`
+2. Check server logs for errors
+3. Test with simple tools first
 
-```bash
-# Clone and install
-git clone https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM.git
-cd mcp-connect
-npm install
-
-# Run example with debug logging
-cd examples/todo-app
-MCP_DEBUG=1 node ../../src/cli.js
+## 📋 Examples
 
-# Test global installation locally
-npm link
-cd /path/to/test/project
-mcp-connect
+### File Operations
+```javascript
+["readFile", async ({ path }) => {
+  const fs = await import('fs/promises');
+  return await fs.readFile(path, 'utf8');
+}]
+```
 
-# Run tests
-npm test
+### API Calls
+```javascript
+["getWeather", async ({ city }) => {
+  const response = await fetch(`https://api.weather.com/${city}`);
+  return await response.json();
+}]
+```
 
-# Lint and format code
-npm run lint
-npm run format
+### Database Queries
+```javascript
+["getUser", async ({ id }) => {
+  // Your database logic here
+  return { id, name: "John Doe", email: "john@example.com" };
+}]
 ```
 
-## 🏗️ Architecture
+## 🌐 Other MCP Clients
 
-- **Pure JavaScript** with JSDoc type annotations
-- **ESM modules** with Node.js 18+ support
-- **Express.js** HTTP server integration
-- **Official MCP SDK** integration
-- **Structured logging** with performance metrics
-- **Comprehensive validation** with user-friendly errors
-- **Pure MCP implementation** focused on STDIO transport
+Claude Desktop setup is covered above. Tutorials for other MCP clients coming soon:
+- VS Code extensions
+- Custom applications
+- Other AI platforms
 
 ## 📄 License
 
-MIT © [myat-kyaw-thu](https://github.com/myat-kyaw-thu)
+MIT © [myat-kyaw-thu](https://github.com/myat-kyaw-thu)

package/package.json

@@ -1,63 +1,63 @@
-{
-  "name": "@myatkyawthu/mcp-connect",
-  "version": "0.1.1",
-  "description": "Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents",
-  "type": "module",
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "exports": {
-    ".": {
-      "import": "./src/index.js",
-      "require": "./src/index.js"
-    }
-  },
-  "bin": {
-    "mcp-connect": "./src/cli.js"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "start": "node src/cli.js",
-    "dev": "nodemon src/cli.js",
-    "test": "node --test",
-    "test:unit": "node --test tests/unit",
-    "test:integration": "node --test tests/integration",
-    "lint": "eslint src/",
-    "format": "prettier --write src/"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "ai",
-    "agents",
-    "tools",
-    "claude",
-    "gpt",
-    "javascript",
-    "nodejs"
-  ],
-  "author": "myat-kyaw-thu",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM.git"
-  },
-  "bugs": {
-    "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM/issues"
-  },
-  "homepage": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.5.0"
-  },
-  "devDependencies": {
-    "nodemon": "^3.0.0",
-    "eslint": "^8.0.0",
-    "prettier": "^3.0.0"
-  }
+{
+  "name": "@myatkyawthu/mcp-connect",
+  "version": "0.2.0",
+  "description": "Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
+  "bin": {
+    "mcp-connect": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "dev": "nodemon src/cli.js",
+    "test": "node --test",
+    "test:unit": "node --test tests/unit",
+    "test:integration": "node --test tests/integration",
+    "lint": "eslint src/",
+    "format": "prettier --write src/"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agents",
+    "tools",
+    "claude",
+    "gpt",
+    "javascript",
+    "nodejs"
+  ],
+  "author": "myat-kyaw-thu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM.git"
+  },
+  "bugs": {
+    "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM/issues"
+  },
+  "homepage": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0"
+  }
 }