MCP Server Kickstart

MCP服务器启动🚀

一个简洁灵活的Java框架，用于快速创建 MCP（模型上下文协议） 服务器-- 支持 流媒体, 上海证券交易所，以及 工作室 运输 无需处理Jetty配置、JSON处理或反射魔法。

特性

• 基于注释的工具 --只需用以下内容注释您的方法 @McpTool 和 @McpParam
• 自动生成JSON模式 -无需手动编写模式
• 三种运输方式

- 流媒体 （默认） - 上海证券交易所 - 工作室

• Fluent Builder API -干净易读的服务器配置
• 强大的反射处理 -支持数组、集合和复杂类型
• 内置Jetty服务器 -包括生产就绪的HTTP服务器（SSE/流模式）
• STDIO服务器 （克劳德桌面，克莱恩）
• 平滑关闭 -应用程序终止时进行适当的清理
• 零配置或最小配置 -合理的默认设置，只需添加您的工具即可

支持的交通工具

此服务器支持 三种MCP传输模式:

如果没有指定标志，服务器将在 流媒体模式.

快速开始

1.克隆和构建

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

2.创建工具类

public class MyTools {
    
    @McpTool("Adds two numbers together")
    public int add(@McpParam(name = "a", description = "First number") int a,
                   @McpParam(name = "b", description = "Second number") int b) {
        return a + b;
    }
    
    @McpTool("Gets information about files in a directory")
    public List listFiles(@McpParam(name = "directory", description = "Directory path") String directory) {
        return Arrays.stream(new File(directory).listFiles())
                     .map(File::getName)
                     .collect(Collectors.toList());
    }
}

3.跑步

3a。“手动”启动服务器

public class MyServer {

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

3b。通过gradle跑步

./gradlew run

您的MCP服务器将在http://localhost:8090/mcp

如果要公开不同的工具，请使用

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

您可以提供多个类名。

3c。从远处的罐子里跑

java -jar mcp-server-kickstart.jar

以流模式启动 加载默认HelloWorldTools

如果要公开不同的工具，请使用

java -jar mcp-server-kickstart.jar --sse com.qaware.mcp.tools.McpSourceTool

3d。使用Docker运行

docker build -t mcp-server-kickstart .
docker run -i --rm mcp-server-kickstart

服务器使用STDIO传输，并通过标准输入/输出进行通信。您可以提供多个工具类名作为参数。

STDIO传输如何工作

在docker中，MCP服务器设置为使用 STDIO（标准输入/输出）传输 而不是HTTP/SSE。这意味着：

1. 基于流程的沟通：MCP客户端将您的服务器作为子进程生成
2. 简单集成：无需管理端口、URL或网络配置
3. 安全：通过管道在同一台机器内进行通信
4. 动态启动：每个MCP客户端会话都会启动一个新的服务器实例
5. Docker友好：易于容器化和独立运行

服务器从以下位置读取MCP协议消息 stdin 并将回复写入 stdout，使其与支持STDIO传输的任何MCP客户端（如Claude Desktop、Cline等）兼容。

调试

服务器记录所有工具注册和请求。

在流媒体或SSE模式下，您将看到如下输出：

INFO  - Creating MCP servlet 'My MCP Server' v1.0.0
INFO  - Registering tools from: MyTools
INFO  - MCP Server started successfully on http://localhost:8090

在STDIO模式下

INFO  - Starting MCP server (STDIO)
INFO  - Registering tools from: MyTools
INFO  - Ready to receive MCP protocol messages

备注：当由MCP客户端（如Claude Desktop）生成时，日志通常会写入客户端的日志目录，而不是您的控制台。检查MCP客户端的文档以了解日志位置。

支持的类型

该框架自动处理以下JSON模式生成：

• 基元：int、long、double、float、boolean
• 字符串：字符串
• 数组：int\[\]、String\[\]等。
• 收藏：列表，设置，收藏

配置

服务器配置

McpServer.create()
    .serverInfo("My Server", "2.0.0")  // Server name and version
    .port(8080)                        // HTTP port (default: 8090)
    .addTool(new MyTools())            // Add tool instances
    .addTool(new MoreTools())          // Add multiple tools
    .start();

工具方法

方法必须用@McpTool（“description”）进行注释

所有参数都必须用@McpParam注释（name=“paramName”，description=“…”）

返回类型会自动进行JSON序列化

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

与MCP客户端集成

码（千码）✅ 已测试

将此添加到您的KiloCode MCP配置中（您需要使用SSE！）：

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

智能J✅ 已测试

地点：

• macOS：~/库/应用程序支持/github-copilot/intellij/mcp.json
• Windows：%APPDATA%\\APPDATA\\Local\\github副本\\intellij\\mcp.json

配置：

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

克劳德桌面（拟人）⚠️ 未经测试的

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

地点：

• macOS：~/库/应用程序支持/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:8090/sse"
      }
    }
  }
}

注意：Claude Desktop配置可能不同-请查看官方Claude MCP文档以了解确切格式。

Docker执行

{
  "mcpServers": {
    "mcp-knowledge-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-server-kickstart:latest",
        "com.qaware.mcp.tools.knowledge.McpKnowledgeTool"
      ]
    }
  }
}

带卷挂载的Docker用于文档

{
  "mcpServers": {
    "mcp-knowledge-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/docs:/data:ro",
        "mcp-server-kickstart:latest",
        "com.qaware.mcp.tools.knowledge.McpKnowledgeTool"
      ]
    }
  }
}

其他MCP客户端

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

任何支持STDIO传输的MCP客户端都可以通过生成进程进行连接：

java -jar mcp-server-kickstart-all-1.0.0.jar [ToolClassName]

看 mcp-config-examples.json 更多配置示例。

例子

学生用函数计算器

public class Calculator {
    
    @McpTool("Performs basic arithmetic operations")
    public double calculate(@McpParam(name = "operation", description = "Operation: +, -, *, /") 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("Unknown operation: " + op);
        };
    }
}

文件操作

public class FileTools {
    
    @McpTool("Reads content from a file")
    public String readFile(@McpParam(name = "path", description = "File path") String path) throws IOException {
        return Files.readString(Paths.get(path));
    }
    
    @McpTool("Lists files in directory")
    public List listDirectory(@McpParam(name = "path") String path) {
        File dir = new File(path);
        return dir.isDirectory() ? Arrays.asList(dir.list()) : List.of();
    }
}

与收藏合作

public class DataTools {
    
    @McpTool("Filters a list of numbers")
    public List filterNumbers(@McpParam(name = "numbers") List numbers,
                                       @McpParam(name = "threshold") int threshold) {
        return numbers.stream()
                     .filter(n -> n > threshold)
                     .collect(Collectors.toList());
    }
}

构建和部署

胖JAR

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

Docker镜像

# Build the image
docker build -t mcp-server-kickstart:latest .

# Run with default tools
docker run -i --rm mcp-server-kickstart:latest

# Run with custom tool
docker run -i --rm mcp-server-kickstart:latest com.example.MyCustomTool

# Run with volume mount
docker run -i --rm -v /path/to/docs:/docs:ro mcp-server-kickstart:latest

需求

• Java 17+
• Gradle 8.14.2+（包装内含）

依赖项

• MCP-SDK: io.modelcontextprotocol.sdk:mcp:0.14.1 -核心MCP协议支持
• 杰克逊: com.fasterxml.jackson.core:jackson-databind:2.17.0 -JSON序列化
• Log4j: org.apache.logging.log4j:log4j-slf4j2-impl:2.24.3 -日志记录
• 高性能路面混凝土: com.carrotsearch:hppc:0.10.0 -高性能原始收藏

注意：Jetty依赖项可以从build.gradle中删除，因为STDIO传输不再需要它们。

许可证

麻省理工学院许可证-欢迎在您的项目中使用！

使用知识和Slurp工具

首先生成jar

./gradlew fatJar

使用STDIO传输与知识和Slurp工具

现在创建或修改您的 mcp.json 配置文件，包括以下服务器定义：

地点：

• macOS：~/库/应用程序支持/github-copilot/intellij/mcp.json
• Windows：%APPDATA%\\APPDATA\\Local\\github副本\\intellij\\mcp.json

{
    "servers": {
        "stdio": {
            "command": "
/bin/java.exe", // or just java
            "args": [
                "-jar",
                "
/mcp-server-kickstart/build/libs/mcp-server-kickstart-all-1.1.0.jar",
                "--stdio",
                "com.qaware.mcp.tools.knowledge.McpKnowledgeTool",
                "com.qaware.mcp.tools.knowledge.McpSlurpTool"
            ],
            "env": {
                "MCP_KB_MAX_CONTENT": "3000",
                "MCP_KB_ROOT": ";"
                // MCP_SLURP_ROOT is deprecated for the slurp tool; provide slurp paths as tool arguments instead
            }
        }
    }
}

此配置确保服务器以 McpKnowledgeTool 和 McpSlurpTool 启用，使用知识库的指定环境变量并将slurp数据路径作为工具参数传递。

利用知识和Slurp工具使用流传输

如果您想手动启动服务器，您首先需要配置环境变量并提供必要的参数。这些工具使服务器能够管理知识数据库并处理各种文档格式。

知识库配置

• 环境变量:

- MCP_KB_ROOT：指定知识库的目录，用 ;. - MCP_KB_MAX_CONTENT：定义非停用词令牌的令牌预算。约2x MCP_KB_MAX_CONTENT 令牌将被发送。根据需要调整此值。

Slurp配置

• 工具参数:

- 这 McpSlurpTool 不再从环境变量中读取slurp根。相反，在启动服务器时，将slurp路径作为参数提供给工具。该工具接受单个路径或以分号分隔的路径列表（例如。 C:\data\docs;D:\more_docs).

这 slurp 该工具将所有支持的文档导入LLM。处理大量数据时要小心。

支持的文档格式

目前，支持以下格式：

• .doc, .docx
• .pdf
• .ppt, .pptx
• .xls, .xlsx

通过扩展Apache Tika的功能，可以支持其他格式。

/bin/java.exe -jar mcp-server-kickstart-all-1.1.0.jar com.qaware.mcp.tools.knowledge.McpKnowledgeTool com.qaware.mcp.tools.knowledge.McpSlurpTool

示例配置 mcp.json

{
"servers": {
        "localhost": {
            "url": "http://localhost:8090/mcp"
        }
    }
}