MCP Server Kickstart 🚀

一个极简的Java框架，用于快速创建MCP（模型上下文协议）服务器，无需处理Jetty配置、JSON处理或反射魔法的麻烦。

特性

• 基于注解的工具 - 只需用@McpTool和@McpParam注解你的方法
• 自动JSON模式生成 - 不需要手动编写模式
• 流畅的构建器API - 清晰易读的服务器配置
• 零配置 - 合理的默认设置，只需添加你的工具即可开始
• 强大的反射处理 - 支持数组、集合和复杂类型
• 内置Jetty服务器 - 包含生产就绪的HTTP服务器
• 优雅的关闭 - 应用程序终止时进行适当的清理

快速入门

1. 克隆并构建

git clone https://github.com/qaware/mcp-server-kickstart.git
cd mcp-server-kickstart
./gradlew build

2. 创建你的工具类

public class MyTools {
    
    @McpTool("将两个数字相加")
    public int add(@McpParam(name = "a", description = "第一个数字") int a,
                   @McpParam(name = "b", description = "第二个数字") int b) {
        return a + b;
    }
    
    @McpTool("获取目录中文件的信息")
    public List<String> listFiles(@McpParam(name = "directory", description = "目录路径") String directory) {
        return Arrays.stream(new File(directory).listFiles())
                     .map(File::getName)
                     .collect(Collectors.toList());
    }
}

3. 启动你的服务器

public class Server {

    public static void main(String[] args) throws Exception {
        McpServer.create()
                 .serverInfo("我的MCP服务器", "1.0.0")
                 .port(8090)
                 .addTool(new MyTools())
                 .start();
    }
}

4. 运行

./gradlew run

你的MCP服务器将在http://localhost:8090/mcp上可用。

如果你想暴露不同的工具，请使用

./gradlew run --args com.qaware.mcp.tools.McpSourceTool

你可以提供多个类名。

调试

服务器记录了所有工具注册和请求。检查控制台输出：

INFO  - 创建MCP Servlet '我的MCP服务器' v1.0.0
INFO  - 注册来自：MyTools 的工具
INFO  - MCP服务器成功启动在 http://localhost:8090

支持的数据类型

框架会自动处理以下数据类型的JSON模式生成：

• 基本类型：int, long, double, float, boolean
• 字符串：String
• 数组：int[], String[] 等
• 集合：List<T>, Set<T>, Collection<T>

配置

服务器配置

McpServer.create()
    .serverInfo("我的服务器", "2.0.0")  // 服务器名称和版本
    .port(8080)                        // HTTP端口（默认：8090）
    .addTool(new MyTools())            // 添加工具实例
    .addTool(new MoreTools())          // 添加多个工具
    .start();

工具方法

方法必须用@McpTool("描述")注解

所有参数都必须用@McpParam(name = "参数名", description = "...")注解

返回类型会被自动JSON序列化

异常会被自动捕获并作为错误响应返回

连接到AI工具

Codeium (KiloCode) ✅ 测试通过

在你的KiloCode MCP配置中添加这行（你需要使用SSE！）：

{
  "mcpServers": {
    "java-kickstart-server": {
      "url": "http://localhost:8090/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "alwaysAllow": ["hello", "add", "getItems"],
      "disabled": false
    }
  }
}

IntelliJ ✅ 测试通过

位置：

• macOS: ~/Library/Application Support/github-copilot/intellij/mcp.json
• Windows: %APPDATA%\AppData\Local\github-copilot\intellij\mcp.json

配置：

{
    "servers": {
        "my-local-server": {
            "url": "http://localhost:8090/mcp",
            "requestInit": {
                "headers": {
                    "Authorization": "Bearer XYZ!"
                }
            }
        }
    }
}

Claude Desktop (Anthropic) ⚠️ 未测试

根据文档，这应该适用于Claude Desktop：

位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "my-java-server": {
      "command": "node",
      "args": ["path/to/your/mcp-server"],
      "env": {
        "SERVER_URL": "http://localhost:8_090/sse"
      }
    }
  }
}

注意：Claude Desktop配置可能有所不同，请查看官方Claude MCP文档以获取确切格式。

通用MCP客户端

任何MCP客户端都应该能够连接到：http://localhost:8090/sse

示例

简单计算器

public class Calculator {
    
    @McpTool("执行基本算术运算")
    public double calculate(@McpParam(name = "operation", description = "操作：+, -, *, /") String op,
                           @McpParam(name = "a") double a,
                           @McpParam(name = "b") double b) {
        return switch (op) {
            case "+" -> a + b;
            case "-" -> a - b;
            case "*" -> a * b;
            case "/" -> a / b;
            default -> throw new IllegalArgumentException("未知操作：" + op);
        };
    }
}

文件操作

public class FileTools {
    
    @McpTool("从文件读取内容")
    public String readFile(@McpParam(name = "path", description = "文件路径") String path) throws IOException {
        return Files.readString(Paths.get(path));
    }
    
    @McpTool("列出目录中的文件")
    public List<String> listDirectory(@McpParam(name = "path") String path) {
        File dir = new File(path);
        return dir.isDirectory() ? Arrays.asList(dir.list()) : List.of();
    }
}

处理集合

public class DataTools {
    
    @McpTool("过滤数字列表")
    public List<Integer> filterNumbers(@McpParam(name = "numbers") List<Integer> numbers,
                                       @McpParam(name = "threshold") int threshold) {
        return numbers.stream()
                     .filter(n -> n > threshold)
                     .collect(Collectors.toList());
    }
}

构建Fat JAR

./gradlew fatJar
java -jar build/libs/mcp-server-kickstart-1.0.0.jar

要求

• Java 17+
• Gradle 8.14.2+ （通过包装器包含）

依赖项

• MCP SDK: io.modelcontextprotocol.sdk:mcp:0.10.0
• Jetty: org.eclipse.jetty:jetty-server:12.0.22
• Jackson: com.fasterxml.jackson.core:jackson-databind:2.16.1
• SLF4J: org.slf4j:slf4j-simple:2.0.9

许可证

MIT许可证 - 欢迎在你的项目中使用！