@myatkyawthu/mcp-connect 0.1.1 → 0.2.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 myat-kyaw-thu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2024 myat-kyaw-thu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,308 +1,170 @@
-# mcp-connect
-
-> Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents
-
-[![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
-
-### Option 1: Global Installation (Recommended)
-
-```bash
-# Install globally with npm
-npm install -g mcp-connect
-```
-
-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:
-
-```bash
-mcp-connect
-```
-
-### Option 2: Local Installation
-
-```bash
-# Install locally with npm
-npm install mcp-connect
-```
-
-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
-
-```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
-
-```javascript
-defineMCP({
-  name: "My MCP Server",      // Required: Server name
-  version: "1.0.0",           // Required: Server version
-  description: "My server",   // Optional: Description
-  tools: [
-    // Your tool definitions
-  ]
-})
-```
-
-## 🔧 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"
-```
-
-## 🛡️ 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
-
-#### Global Installation (Recommended)
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "my-app": {
-      "command": "mcp-connect",
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-#### Local Installation
-
-```json
-{
-  "mcpServers": {
-    "my-app": {
-      "command": "npx",
-      "args": ["mcp-connect"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-#### Alternative: Package Script
-
-Add to your project's `package.json`:
-
-```json
-{
-  "scripts": {
-    "mcp": "mcp-connect"
-  }
-}
-```
-
-Then in Claude Desktop config:
-
-```json
-{
-  "mcpServers": {
-    "my-app": {
-      "command": "npm",
-      "args": ["run", "mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-### Other MCP Clients
-
-Any MCP-compliant client can connect using the STDIO transport. The server implements the full MCP specification with:
-
-- `tools/list` - List available tools
-- `tools/call` - Execute tool functions
-- Proper JSON-RPC 2.0 messaging
-- Standard MCP lifecycle management
-
-## 📁 Examples
-
-### Todo App Example
-
-```javascript
-import { defineMCP } from "mcp-connect";
-
-const todos = [{ id: 1, title: "Buy milk", completed: false }];
-
-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;
-      }
-    }
-  ]
-});
-```
-
-Check out the [examples](./examples) directory for complete working examples.
-
-## 🛠 Development
-
-```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
-
-# Test global installation locally
-npm link
-cd /path/to/test/project
-mcp-connect
-
-# Run tests
-npm test
-
-# Lint and format code
-npm run lint
-npm run format
-```
-
-## 🏗️ Architecture
-
-- **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
-
-## 📄 License
-
-MIT © [myat-kyaw-thu](https://github.com/myat-kyaw-thu)
+# mcp-connect
+
+> Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents
+
+[![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)
+
+## 🚀 Claude Desktop Setup (5 Minutes)
+
+### Step 1: Install mcp-connect
+
+```bash
+npm install -g @myatkyawthu/mcp-connect
+```
+### Step 2: Create mcp.config.js
+
+### Step 2: Create Your MCP Server
+
+```bash
+# Navigate to your project directory
+cd your-project
+
+# Generate sample config
+mcp-connect init
+```
+
+This creates `mcp.config.js` with example tools:
+
+```javascript
+import { defineMCP } from "@myatkyawthu/mcp-connect";
+
+export default defineMCP({
+  name: "My MCP App",
+  version: "1.0.0",
+  tools: [
+    ["hello", async ({ name = "World" }) => `Hello ${name}!`],
+    ["echo", async ({ message }) => `Echo: ${message}`]
+  ]
+});
+```
+### Step 3: Test Locally
+
+### Step 3: Configure Claude Desktop
+
+Open Claude Desktop config file:
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Add your MCP server:
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "mcp-connect",
+      "args": ["C:/full/path/to/your/mcp.config.js"]
+    }
+  }
+}
+```
+
+**Important**: Use the full absolute path to your `mcp.config.js` file.
+
+### Step 4: Start & Test
+
+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"*
+
+✅ **Done!** Your functions are now available to Claude Desktop.
+
+---
+
+## 📖 Tool Definition Guide
+
+### Simple Format (Recommended)
+
+```javascript
+// Just name and function
+["toolName", async (args) => "result"]
+```
+## 🔧 CLI Usage
+
+### Advanced Format (With Validation)
+
+```javascript
+{
+  name: "toolName",
+  description: "What this tool does",
+  schema: {
+    type: "object",
+    properties: {
+      param: { type: "string", description: "Parameter description" }
+    },
+    required: ["param"]
+  },
+  handler: async ({ param }) => `Result: ${param}`
+}
+```
+
+## 🛠 Development Commands
+
+```bash
+# Start with auto-reload during development
+npm run dev
+
+# Start server with specific config file
+mcp-connect /path/to/your/mcp.config.js
+
+# Format code
+npm run format
+
+# Lint code
+npm run lint
+```
+
+## 🔧 Troubleshooting
+
+### Config File Not Found
+```bash
+# Create sample config
+mcp-connect init
+```
+
+### Claude Desktop Not Connecting
+1. Check config file path is absolute
+2. Restart Claude Desktop completely
+3. Check Claude Desktop logs for errors
+
+### Tool Not Working
+1. Verify tool syntax in `mcp.config.js`
+2. Check server logs for errors
+3. Test with simple tools first
+
+## 📋 Examples
+
+### File Operations
+```javascript
+["readFile", async ({ path }) => {
+  const fs = await import('fs/promises');
+  return await fs.readFile(path, 'utf8');
+}]
+```
+
+### API Calls
+```javascript
+["getWeather", async ({ city }) => {
+  const response = await fetch(`https://api.weather.com/${city}`);
+  return await response.json();
+}]
+```
+
+### Database Queries
+```javascript
+["getUser", async ({ id }) => {
+  // Your database logic here
+  return { id, name: "John Doe", email: "john@example.com" };
+}]
+```
+
+## 🌐 Other MCP Clients
+
+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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myatkyawthu/mcp-connect",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "mcp-connect": "./src/cli.js"
+    "mcp-connect": "src/cli.js"
   },
   "files": [
     "src",
@@ -43,7 +43,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM.git"
+    "url": "git+https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM.git"
   },
   "bugs": {
     "url": "https://github.com/myat-kyaw-thu/MCP_Indigration_Package-NPM/issues"