@myatkyawthu/mcp-connect 0.1.1

package/LICENSE

@@ -0,0 +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
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# 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)

package/package.json

@@ -0,0 +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"
+  }
+}

package/src/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { defineMCP } from "./defineMCP.js";
+import { MCPConnectServer } from "./server/mcpServer.js";
+
+/**
+ * CLI entry point for mcp-connect
+ * Uses MCP SDK with STDIO transport or Express.js for HTTP transport
+ */
+async function main() {
+  try {
+    console.error("Starting MCP-Connect CLI...");
+
+    // Check if config file path is provided as argument
+    const configArg = process.argv[2];
+    /** @type {string|null} */
+    let configPath = null;
+
+    if (configArg) {
+      // Config file path provided as argument
+      const fullPath = resolve(configArg);
+      if (existsSync(fullPath)) {
+        configPath = fullPath;
+      } else {
+        console.error(`Config file not found: ${configArg}`);
+        process.exit(1);
+      }
+    } else {
+      // Look for config file in current directory (prioritize .js and .mjs)
+      const configPaths = ["mcp.config.js", "mcp.config.mjs", "mcp.config.ts"];
+
+      for (const path of configPaths) {
+        const fullPath = resolve(process.cwd(), path);
+        if (existsSync(fullPath)) {
+          configPath = fullPath;
+          break;
+        }
+      }
+    }
+
+    if (!configPath) {
+      console.error("No MCP config file found. Create mcp.config.js in your project root.");
+      console.error("Example config:");
+      console.error(`
+import { defineMCP } from "mcp-connect"
+
+export default defineMCP({
+  name: "My App",
+  version: "1.0.0",
+  tools: [
+    ["hello", async ({ name }) => \`Hello \${name}!\`]
+  ]
+})
+      `);
+      process.exit(1);
+    }
+
+    console.error(`Loading config from: ${configPath}`);
+
+    let configModule;
+    try {
+      // Handle TypeScript config files
+      if (configPath.endsWith(".ts")) {
+        console.error("TypeScript config detected. For Node.js compatibility:");
+        console.error("1. Rename mcp.config.ts to mcp.config.js and convert to JavaScript");
+        console.error("2. Or install tsx: npm install tsx");
+        console.error("3. Then run with: npx tsx src/cli.js");
+        console.error("");
+        console.error("JavaScript example:");
+        console.error(`
+// mcp.config.js
+import { defineMCP } from "mcp-connect";
+
+export default defineMCP({
+  name: "My App",
+  version: "1.0.0",
+  tools: [
+    ["hello", async ({ name }) => \`Hello \${name}!\`]
+  ]
+});
+        `);
+        process.exit(1);
+      }
+
+      // Import config file using Node.js ES modules
+      const fileUrl = configPath.startsWith('/')
+        ? `file://${configPath}`
+        : `file:///${configPath.replace(/\\/g, '/')}`;
+
+      configModule = await import(fileUrl);
+    } catch (error) {
+      console.error("Failed to load config file:");
+      if (error instanceof Error) {
+        console.error("Error:", error.message);
+
+        if (error.message.includes("Cannot resolve") || error.message.includes("MODULE_NOT_FOUND")) {
+          console.error("Make sure 'mcp-connect' is installed: npm install mcp-connect");
+        } else if (error.message.includes("SyntaxError")) {
+          console.error("Config file has syntax errors. Check your JavaScript syntax.");
+        } else if (error.message.includes("ERR_MODULE_NOT_FOUND")) {
+          console.error("Module import error. Check your import paths in the config file.");
+        }
+      }
+      process.exit(1);
+    }
+
+    const config = configModule.default;
+
+    if (!config) {
+      console.error("Config file must export a default configuration");
+      console.error("Make sure your config has: export default defineMCP({...})");
+      process.exit(1);
+    }
+
+    // Validate config using defineMCP (in case user didn't use it)
+    let validatedConfig;
+    try {
+      validatedConfig = typeof config === "function" ? config : defineMCP(config);
+    } catch (error) {
+      console.error("Configuration validation failed:", error);
+      process.exit(1);
+    }
+
+    // Create and start MCP server
+    const server = new MCPConnectServer(validatedConfig);
+    await server.start();
+
+    // Handle graceful shutdown
+    process.on("SIGINT", async () => {
+      console.error("Shutting down...");
+      try {
+        await server.stop();
+      } catch (error) {
+        console.error("Error during shutdown:", error);
+      }
+      process.exit(0);
+    });
+
+    process.on("SIGTERM", async () => {
+      console.error("Shutting down...");
+      try {
+        await server.stop();
+      } catch (error) {
+        console.error("Error during shutdown:", error);
+      }
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error("Failed to start MCP server:", error);
+    process.exit(1);
+  }
+}
+
+// Run CLI if this file is executed directly
+// Multiple checks to ensure main() runs when CLI is executed
+const isMainModule = process.argv[1] && (
+  import.meta.url === `file://${process.argv[1]}` ||
+  import.meta.url.endsWith(process.argv[1]) ||
+  process.argv[1].endsWith('cli.js') ||
+  process.argv[1].includes('mcp-connect')
+);
+
+if (isMainModule) {
+  main().catch((error) => {
+    console.error("CLI startup failed:", error);
+    process.exit(1);
+  });
+}

package/src/defineMCP.js

@@ -0,0 +1,72 @@
+import { formatValidationErrors, validateConfig } from "./utils/configValidation.js";
+import { logger } from "./utils/logger.js";
+
+/**
+ * Define MCP configuration with tools and server settings
+ * This is the main user-facing API that converts simple tool definitions
+ * into MCP-compliant format with comprehensive validation
+ * 
+ * @param {Object} config - Configuration object
+ * @param {string} config.name - Server name
+ * @param {string} config.version - Server version
+ * @param {string} [config.description] - Server description
+ * @param {import('./types/mcp.js').ToolDefinition[]} config.tools - Tool definitions
+ * @returns {import('./types/mcp.js').MCPConfig} MCP configuration object
+ * @throws {Error} If configuration is invalid
+ */
+export function defineMCP(config) {
+  // Comprehensive configuration validation
+  const validationResult = validateConfig(config);
+
+  if (!validationResult.isValid) {
+    const errorMessage = formatValidationErrors(validationResult);
+    logger.error("Configuration validation failed", errorMessage);
+    throw new Error(`Invalid MCP configuration:\n${errorMessage}`);
+  }
+
+  // Log warnings if any
+  if (validationResult.warnings.length > 0) {
+    const warningMessage = formatValidationErrors({ isValid: true, errors: [], warnings: validationResult.warnings });
+    logger.warn("Configuration warnings", warningMessage);
+  }
+
+  // Convert validated tool definitions to MCP format
+  /** @type {import('./types/mcp.js').MCPTool[]} */
+  const mcpTools = config.tools.map((tool) => {
+    if (Array.isArray(tool)) {
+      // Handle [name, function] format
+      const [name, handler] = tool;
+      return {
+        name: name.trim(),
+        description: `Tool: ${name}`,
+        inputSchema: {
+          type: "object",
+          properties: {},
+          additionalProperties: true,
+        },
+        handler,
+      };
+    } else {
+      // Handle object format
+      const { name, handler, description, schema } = tool;
+      return {
+        name: name.trim(),
+        description: description || `Tool: ${name}`,
+        inputSchema: schema || {
+          type: "object",
+          properties: {},
+          additionalProperties: true,
+        },
+        handler,
+      };
+    }
+  });
+
+  // Return MCP-compliant config
+  return {
+    name: config.name,
+    version: config.version,
+    description: config.description,
+    tools: mcpTools,
+  };
+}

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * MCP-Connect - Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents
+ * 
+ * Main entry point - exports public API
+ * 
+ * @example
+ * ```javascript
+ * import { defineMCP } from 'mcp-connect';
+ * 
+ * export default defineMCP({
+ *   name: 'My App',
+ *   version: '1.0.0',
+ *   tools: [
+ *     ['hello', async ({ name }) => `Hello ${name}!`]
+ *   ]
+ * });
+ * ```
+ */
+
+// Main API exports
+export { defineMCP } from "./defineMCP.js";
+export { MCPConnectServer } from "./server/mcpServer.js";
+
+// Type validation utilities (for runtime type checking)
+export {
+  isValidMCPConfig, isValidMCPTool, isValidToolDefinition
+} from "./types/mcp.js";
+
+/**
+ * @typedef {import('./types/mcp.js').MCPConfig} MCPConfig
+ * @typedef {import('./types/mcp.js').MCPTool} MCPTool  
+ * @typedef {import('./types/mcp.js').ToolDefinition} ToolDefinition
+ * @typedef {import('./types/mcp.js').MCPServerOptions} MCPServerOptions
+ * @typedef {import('./types/mcp.js').ToolFunction} ToolFunction
+ */