hono-mcp 1.3.0 → 1.4.1

package/README.md

@@ -1,249 +1,51 @@
 # Hono MCP Server
 
-一个基于 [Hono](https://hono.dev/) 构建的 Model Context Protocol (MCP) 服务器，支持多种部署方式。
+基于 Hono 的 Model Context Protocol (MCP) 服务器，支持装饰器模式定义工具，支持 stdio 和 HTTP 两种模式。
 
-## ✨ 特性
-
-- 🎯 **装饰器模式**：使用 TypeScript 装饰器优雅地定义 MCP 工具
-- 🚀 **多种部署方式**：支持 Vercel 部署和本地 CLI 运行
-- 🔧 **统一命令接口**：通过 `executeCommand` 和 `help` 两个工具管理所有命令
-- 📦 **即插即用**：通过 `npx` 快速启动，无需复杂配置
-- 🛡️ **类型安全**：使用 TypeScript 和 Zod 进行类型检查和验证
-- 🎨 **易于扩展**：添加新命令只需创建新的装饰器类
-
-## 📦 安装
-
-### 通过 npx 直接运行（推荐）
+## 安装
 
 ```bash
 npx hono-mcp
 ```
 
-### 全局安装
+## 使用
 
-```bash
-npm install -g hono-mcp
-hono-mcp
-```
-
-### 作为项目依赖安装
+### CLI 模式
 
 ```bash
-npm install hono-mcp
-npx hono-mcp
-```
-
-## 🚀 使用方法
-
-### 命令行使用
-
-```bash
-# 使用默认配置（端口 3000）
-npx hono-mcp
+# HTTP 模式（默认）
+npx hono-mcp --mode http --port 3000
 
-# 指定端口
-npx hono-mcp --port 8080
-
-# 指定主机
-npx hono-mcp --host localhost
-
-# 指定环境
-npx hono-mcp --env development
-
-# 组合使用
-npx hono-mcp --port 8080 --host localhost --env development
-
-# 查看帮助
-npx hono-mcp --help
+# stdio 模式
+npx hono-mcp --mode stdio
 ```
 
-### 环境变量
-
-```bash
-# 设置端口
-export PORT=8080
-npx hono-mcp
-
-# 设置主机
-export HOST=localhost
-npx hono-mcp
-
-# 设置环境
-export NODE_ENV=development
-npx hono-mcp
-```
-
-## 🌐 部署方式
-
-### 方式 1：Vercel 部署
-
-1. **克隆项目**
+### Vercel 部署
 
 ```bash
 git clone https://github.com/Fromsko/hono-mcp-remote-server.git
 cd hono-mcp-remote-server
-```
-
-2. **安装依赖**
-
-```bash
 bun install
-```
-
-3. **本地开发**
-
-```bash
-bun run dev:vercel
-```
-
-4. **部署到 Vercel**
-
-```bash
 vc deploy
 ```
 
-或者通过 Vercel Dashboard 连接 GitHub 仓库进行自动部署。
-
-### 方式 2：本地服务器
-
-1. **克隆项目**
-
-```bash
-git clone https://github.com/Fromsko/hono-mcp-remote-server.git
-cd hono-mcp-remote-server
-```
-
-2. **安装依赖**
-
-```bash
-bun install
-```
-
-3. **构建项目**
+## 功能
 
-```bash
-bun run build
-```
+- **装饰器模式**：使用 TypeScript 装饰器优雅定义 MCP 工具
+- **双模式支持**：stdio 和 HTTP 两种传输方式
+- **即插即用**：npx 直接运行，无需配置
+- **类型安全**：TypeScript + Zod 验证
 
-4. **启动服务器**
+## 可用命令
 
-```bash
-bun run start
-```
+- `executeCommand` - 执行任意命令
+- `help` - 查看帮助信息
 
-或者使用 npx：
+## 开发
 
 ```bash
-npx hono-mcp --port 3000
-```
-
-## 📡 API 端点
-
-- **GET `/`** - 服务器信息和可用工具列表
-- **POST `/mcp/*`** - MCP 协议端点，用于工具执行
-- **GET `/help`** - 查看所有可用命令的帮助信息
-- **GET `/vscode`** - VS Code 设置示例
-
-## 🔧 开发
-
-### 本地开发
-
-```bash
-# 安装依赖
 bun install
-
-# 开发模式（CLI）
-bun run dev
-
-# 开发模式（Vercel）
-bun run dev:vercel
-
-# 构建
-bun run build
-
-# 启动生产服务器
-bun run start
-```
-
-### 添加新命令
-
-使用装饰器模式创建新命令非常简单：
-
-```typescript
-import { Command, Param } from '../decorators/command.js'
-import { z } from 'zod'
-import type { CommandHandler } from '../decorators/command.js'
-
-@Command('math.square', 'Calculate the square of a number')
-export class SquareCommand implements CommandHandler {
-  @Param(z.number().describe('The number to square'))
-  number!: number
-
-  async execute() {
-    const result = this.number * this.number
-    return {
-      content: [{ type: 'text', text: `${this.number}² = ${result}` }],
-    }
-  }
-}
+bun run dev        # CLI 开发
+bun run dev:vercel # Vercel 开发
+bun run build      # 构建
 ```
-
-然后在 `src/index.ts` 中导入该命令：
-
-```typescript
-import './commands/math.js'
-import './commands/your-new-command.js'
-```
-
-## 📖 使用 MCP 服务器
-
-### 通过 executeCommand 工具
-
-```json
-{
-  "type": "math.add",
-  "params": {
-    "a": 5,
-    "b": 3
-  }
-}
-```
-
-### 通过 help 工具
-
-查看所有可用命令及其描述。
-
-## 🎯 可用命令
-
-当前支持以下数学运算命令：
-
-- `math.add` - 加法运算
-- `math.subtract` - 减法运算
-- `math.multiply` - 乘法运算
-- `math.divide` - 除法运算
-
-## 📚 设计文档
-
-详细的设计文档请参考：[MCP 装饰器模式设计文档](./docs/MCP-装饰器模式设计文档.md)
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 📄 许可证
-
-MIT License
-
-## 🔗 相关链接
-
-- [Hono 文档](https://hono.dev/)
-- [MCP 协议规范](https://modelcontextprotocol.io/)
-- [mcp-handler](https://github.com/modelcontextprotocol/typescript-sdk)
-
-## 📞 联系方式
-
-作者: fromsko
-
----
-
-**提示**: 使用 `npx hono-mcp --help` 查看完整的命令行选项。

package/dist/cli.js

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
-import { serve } from '@hono/node-server';
-import app from './index.js';
+import { serve } from "@hono/node-server";
+import app from "./index.js";
+import { runStdioServer } from "./stdio.js";
 function parseArgs() {
     const args = process.argv.slice(2);
     const options = {};
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (arg === '--port' || arg === '-p') {
+        if (arg === "--port" || arg === "-p") {
             options.port = parseInt(args[++i], 10);
         }
-        else if (arg === '--host' || arg === '-h') {
+        else if (arg === "--host" || arg === "-h") {
             options.host = args[++i];
         }
-        else if (arg === '--env') {
+        else if (arg === "--env") {
             options.env = args[++i];
         }
-        else if (arg === '--help' || arg === '-help') {
+        else if (arg === "--mode") {
+            options.mode = args[++i];
+        }
+        else if (arg === "--help" || arg === "-help") {
             console.log(`
 Usage: hono-mcp [options]
 
@@ -23,13 +27,37 @@ Options:
   --port, -p <port>       Port to listen on (default: 3000)
   --host, -h <host>       Host to bind to (default: 0.0.0.0)
   --env <environment>     Environment: development or production (default: production)
+  --mode <mode>           Mode: stdio or http (default: http)
   --help, -help           Show this help message
 
 Examples:
-  hono-mcp                          # Start server on default port 3000
-  hono-mcp --port 8080              # Start server on port 8080
-  hono-mcp --port 8080 --host localhost  # Start on localhost:8080
+  hono-mcp                          # Start HTTP server on default port 3000
+  hono-mcp --mode stdio             # Start in stdio mode (for MCP clients)
+  hono-mcp --port 8080              # Start HTTP server on port 8080
+  hono-mcp --port 8080 --host localhost  # Start HTTP on localhost:8080
   hono-mcp --env development        # Start in development mode
+
+MCP Configuration (Claude Desktop):
+
+  HTTP Mode:
+  {
+    "mcpServers": {
+      "hono-mcp": {
+        "command": "bunx",
+        "args": ["-y", "hono-mcp@latest"]
+      }
+    }
+  }
+
+  Stdio Mode (default):
+  {
+    "mcpServers": {
+      "hono-mcp": {
+        "command": "bunx",
+        "args": ["-y", "hono-mcp@latest"]
+      }
+    }
+  }
       `);
             process.exit(0);
         }
@@ -38,43 +66,53 @@ Examples:
 }
 async function main() {
     const options = parseArgs();
-    const port = options.port || parseInt(process.env.PORT || '3000', 10);
-    const host = options.host || process.env.HOST || '0.0.0.0';
-    const env = options.env || process.env.NODE_ENV || 'production';
-    console.log(`🚀 Starting Hono MCP Server...`);
-    console.log(`📦 Environment: ${env}`);
-    console.log(`🌐 Host: ${host}`);
-    console.log(`🔌 Port: ${port}`);
-    console.log(`📡 MCP Endpoint: http://${host}:${port}/mcp`);
-    console.log(`📖 Help: http://${host}:${port}/help`);
-    console.log('');
-    try {
-        const server = await serve({
-            fetch: app.fetch,
-            port,
-            hostname: host,
-        });
-        console.log(`✅ Server is running!`);
+    const mode = options.mode || "stdio";
+    if (mode === "stdio") {
+        console.log(`🚀 Starting Hono MCP Server in stdio mode...`);
         console.log(``);
-        console.log(`Press Ctrl+C to stop the server`);
-        process.on('SIGINT', () => {
-            console.log('\n\n🛑 Shutting down server...');
-            server.close(() => {
-                console.log('✅ Server stopped');
-                process.exit(0);
+        await runStdioServer();
+    }
+    else {
+        const port = options.port || parseInt(process.env.PORT || "3000", 10);
+        const host = options.host || process.env.HOST || "0.0.0.0";
+        const env = options.env ||
+            process.env.NODE_ENV ||
+            "production";
+        console.log(`🚀 Starting Hono MCP Server...`);
+        console.log(`📦 Environment: ${env}`);
+        console.log(`🌐 Host: ${host}`);
+        console.log(`🔌 Port: ${port}`);
+        console.log(`📡 MCP Endpoint: http://${host}:${port}/mcp`);
+        console.log(`📖 Help: http://${host}:${port}/help`);
+        console.log("");
+        try {
+            const server = serve({
+                fetch: app.fetch,
+                port,
+                hostname: host,
             });
-        });
-        process.on('SIGTERM', () => {
-            console.log('\n\n🛑 Shutting down server...');
-            server.close(() => {
-                console.log('✅ Server stopped');
-                process.exit(0);
+            console.log(`✅ Server is running!`);
+            console.log(``);
+            console.log(`Press Ctrl+C to stop the server`);
+            process.on("SIGINT", () => {
+                console.log("\n\n🛑 Shutting down server...");
+                server.close(() => {
+                    console.log("✅ Server stopped");
+                    process.exit(0);
+                });
             });
-        });
-    }
-    catch (error) {
-        console.error('❌ Failed to start server:', error);
-        process.exit(1);
+            process.on("SIGTERM", () => {
+                console.log("\n\n🛑 Shutting down server...");
+                server.close(() => {
+                    console.log("✅ Server stopped");
+                    process.exit(0);
+                });
+            });
+        }
+        catch (error) {
+            console.error("❌ Failed to start server:", error);
+            process.exit(1);
+        }
     }
 }
 main();

package/dist/index.js

@@ -1,6 +1,6 @@
-import 'reflect-metadata';
 import { Hono } from "hono";
 import { createMcpHandler } from "mcp-handler";
+import 'reflect-metadata';
 import vscodeSettings from './data/vscode-settings.json' with { type: 'json' };
 import { executeCommandTool, helpTool } from "./tools/decorator-tools.js";
 import './commands/math.js';

package/dist/stdio.js

@@ -0,0 +1,22 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import "reflect-metadata";
+import "./commands/math.js";
+import { executeCommandTool, helpTool } from "./tools/decorator-tools.js";
+async function runStdioServer() {
+    const server = new McpServer({
+        name: "hono-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const tools = [executeCommandTool, helpTool];
+    tools.forEach((tool) => {
+        tool(server);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+export { runStdioServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "MCP server built with Hono - supports both Vercel deployment and npx CLI usage",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,10 @@
     "build": "tsc",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
-    "dev:vercel": "tsx src/index.ts"
+    "dev:vercel": "tsx src/index.ts",
+    "build:linux": "bun build src/cli.ts --compile --target=bun-linux-x64 --outfile=dist/hono-mcp-linux",
+    "build:windows": "bun build src/cli.ts --compile --target=bun-windows-x64 --outfile=dist/hono-mcp.exe",
+    "build:all": "bun run build:linux && bun run build:windows"
   },
   "keywords": [
     "mcp",
@@ -43,7 +46,11 @@
   },
   "devDependencies": {
     "@types/node": "^20.11.17",
+    "terser-webpack-plugin": "^5.3.16",
+    "ts-loader": "^9.5.4",
     "tsx": "^4.7.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "webpack": "^5.104.1",
+    "webpack-cli": "^6.0.1"
   }
 }