Dscope Camel MCP

Apache Camel MCP组件

Apache Camel 4扩展程序 模型上下文协议（MCP） 通过JSON-RPC，代理和自动化可以将Camel路由称为工具。

项目主页：https://github.com/dscope-io/dscope-camel-mcp#readme

🏷 存储库元数据

• 说明： Apache Camel MCP组件支持HTTP/WebSocket上的模型上下文协议客户端/服务器路由。
• 话题： ai-integration, apache-camel, camel-component, java, json-rpc, mcp, model-context-protocol

_注意：这些值反映了GitHub存储库设置（描述、主题、主页）。更新项目元数据时，保持两者同步。_

📦 版本

Maven中心：

• https://central.sonatype.com/artifact/io.dscope.camel/camel-mcp
• https://repo1.maven.org/maven2/io/dscope/camel/camel-mcp/

📋 需求

• Java 21+
• Maven 3.9+
• 阿帕奇骆驼4.20.0+

🚀 特性

• 生产者（客户）模式：通过以下方式将MCP JSON-RPC请求发送到远程服务器 to("mcp:http://host/mcp?method=tools/list").
• 消费者（服务器）模式：暴露MCP端点 from("mcp:http://0.0.0.0:3000/mcp") --内置请求验证、JSON-RPC解析、速率限制和响应序列化。
• 实施核心MCP方法： initialize, ping, resources/list, resources/read, resources/get, tools/list, tools/call, health，以及 stream.
• MCP应用桥支持: ui/initialize, ui/message, ui/update-model-context，以及 ui/tools/call 用于嵌入式UI集成。
• 通知: notifications/initialized, notifications/cancelled, notifications/progress.
• 生产者和消费者模式的HTTP和WebSocket传输。
• 提供20多个用于JSON-RPC信封、工具目录、资源目录和通知工作流的注册表处理器。
• Apache Karavan集成：为拖放MCP路线构建生成可视化设计器元数据。
• 骆驼模具支持: @UriEndpoint-基于组件描述符的生成(mcp.json)用于IDE自动补全和文档。
• 两个示例项目和Postman集合，用于端到端地执行MCP流程。

📖 开发指南 -了解如何使用YAML和Java路由构建自己的MCP服务。

🛠 安装

Maven依赖（发布）

  io.dscope.camel
  camel-mcp
  1.5.0

Gradle依赖（发布）

dependencies {
  implementation "io.dscope.camel:camel-mcp:1.5.0"
}

从源构建（快照）

git clone https://github.com/dscope-io/dscope-camel-mcp.git
cd dscope-camel-mcp
mvn clean install

🔧 配置

URI格式

生产者（客户）模式：

mcp:http://host:port/mcp?method=tools/list
mcp:camel:direct:localMcpRoute?method=tools/list

消费者（服务器）模式：

mcp:http://host:port/path
mcp:http://host:port/path?websocket=true

配置选项

生产者模式

交换机构应该是 Map 代表MCP params生产商通过以下方式丰富了它 jsonrpc, id，以及配置 method 在调用下游HTTP端点之前。

您可以覆盖端点 method 每条带标头的消息 CamelMcpMethod.

对于作为Camel路由公开的本地MCP服务，请使用URI前缀 camel: 之后 mcp:. 调度由端点URI结构选择：

• mcp:camel: ->当地骆驼路线调度（正在进行中）
• mcp:http://... / mcp:https://... ->远程JSON传输调度

Java路由的本地调度示例：

from("direct:start")
  .setBody(constant(Map.of("clientInfo", Map.of("name", "local-client", "version", "1.0.0"))))
  .to("mcp:camel:direct:localMcpService?method=initialize")
  .log("${body}");

远程与本地生产者（YAML）

远程MCP生产者路线：

- route:
    id: remote-mcp-client
    from:
      uri: "direct:remoteMcp"
      steps:
        - setBody:
            constant:
              clientInfo:
                name: "camel-client"
                version: "1.0.0"
        - to:
            uri: "mcp:http://localhost:8080/mcp?method=initialize"
        - setBody:
            simple: "${body[result]}"

本地MCP生产商路线+本地服务路线：

- route:
    id: local-mcp-client
    from:
      uri: "direct:localMcpClient"
      steps:
        - setBody:
            constant:
              probe: true
        - to:
            uri: "mcp:camel:direct:localMcpService?method=ping"
        - setBody:
            simple: "${body[result]}"

- route:
    id: local-mcp-service
    from:
      uri: "direct:localMcpService"
      steps:
        - setBody:
            simple: |
              {
                "jsonrpc": "2.0",
                "id": "${body[id]}",
                "result": {
                  "method": "${body[method]}",
                  "pong": true,
                  "local": true
                }
              }
        - unmarshal:
            json:
              library: Jackson

Java助手API

使用 io.dscope.camel.mcp.McpClient 对于返回MCP的Java友好调用 result 直接有效载荷：

ProducerTemplate template = camelContext.createProducerTemplate();
String endpoint = "mcp:http://localhost:8080/mcp?method=initialize";

Object pingResult = McpClient.pingResult(template, endpoint);
Object toolsResult = McpClient.toolsListResult(template, endpoint);
JsonNode pingJson = McpClient.pingResultJson(template, endpoint);
JsonNode toolsJson = McpClient.toolsListResultJson(template, endpoint);

Object initializeResult = McpClient.callResult(
  template,
  endpoint,
  "initialize",
  Map.of("clientInfo", Map.of("name", "java-client", "version", "1.0.0"))
);

JsonNode initializeJson = McpClient.callResultJson(
  template,
  endpoint,
  "initialize",
  Map.of("clientInfo", Map.of("name", "java-client", "version", "1.0.0"))
);

消费者模式

消费者创建一个HTTP或WebSocket服务器端点，该端点：

1. 验证传入请求（标头、内容类型）
2. 解析JSON-RPC信封
3. 提取方法和参数以交换属性
4. 通往处理器的路径
5. 将响应序列化为JSON

消费者设置的交换属性：

• mcp.jsonrpc.type -请求、通知或回复
• mcp.jsonrpc.id -响应的请求ID
• mcp.jsonrpc.method -正在调用MCP方法
• mcp.tool.name -工具名称（用于工具/调用）

� WebSocket传输

该组件支持用于持久双向MCP会话的WebSocket连接。这非常适合：

• 长时间运行的代理会话
• 流媒体响应
• 实时通知

端点

WebSocket路由配置

示例服务通过Undertow配置WebSocket：

- route:
    id: mcp-service-ws
    from:
      uri: "undertow:ws://0.0.0.0:8090/mcp?sendToAll=false&allowedOrigins=*&exchangePattern=InOut"

与wscat连接

# Install wscat (one-time)
npm install -g wscat

# Connect to MCP WebSocket
npx wscat -c ws://localhost:8090/mcp

替代WebSocket客户端

• 网站位置: websocat ws://localhost:8090/mcp
• VS代码：安装“WebSocket客户端”扩展
• 邮递员：从导入WebSocket集合 samples/mcp-service/postman/
• python：使用 websockets 图书馆
• JavaScript：本地 WebSocket API或 ws 包裹

Python示例

import asyncio
import websockets
import json

async def mcp_client():
    async with websockets.connect('ws://localhost:8090/mcp') as ws:
        # Initialize session
        await ws.send(json.dumps({
            "jsonrpc": "2.0",
            "id": "1",
            "method": "initialize",
            "params": {
                "protocolVersion": "2024-11-05",
                "clientInfo": {"name": "python-client", "version": "1.0.0"}
            }
        }))
        print(await ws.recv())
        
        # List tools
        await ws.send(json.dumps({
            "jsonrpc": "2.0",
            "id": "2",
            "method": "tools/list"
        }))
        print(await ws.recv())

asyncio.run(mcp_client())

JavaScript/Node.js示例

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:8090/mcp');

ws.on('open', () => {
    // Initialize session
    ws.send(JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "initialize",
        params: {
            protocolVersion: "2024-11-05",
            clientInfo: { name: "node-client", version: "1.0.0" }
        }
    }));
});

ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
});

�📚 用法示例

通过curl调用MCP方法

所有MCP方法都使用JSON-RPC 2.0格式。以下是如何调用每个支持的方法：

initialize -启动MCP会话

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }' \
  http://localhost:8080/mcp | jq '.'

ping -健康检查

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "id": "2", "method": "ping"}' \
  http://localhost:8080/mcp | jq '.'

tools/list -列出可用工具

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "id": "3", "method": "tools/list"}' \
  http://localhost:8080/mcp | jq '.'

resources/list -列出可用资源

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "id": "4", "method": "resources/list"}' \
  http://localhost:8080/mcp | jq '.'

tools/call -执行工具

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello from MCP!"
      }
    }
  }' \
  http://localhost:8080/mcp | jq '.'

resources/get -获取资源

# JSON resource
curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "resources/get",
    "params": {
      "resource": "example-resource"
    }
  }' \
  http://localhost:8080/mcp | jq '.'

# Binary resource (returns base64)
curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "id": "6", "method": "resources/get", "params": {"resource": "sample-image.jpg"}}' \
  http://localhost:8080/mcp | jq '.'

MCP应用程序桥（UI方法）

该组件支持 MCP应用桥 在AI代理工作流中嵌入交互式UI的规范。

ui/initialize -启动UI会话

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ui-1",
    "method": "ui/initialize",
    "params": {
      "clientInfo": {"name": "my-ui", "version": "1.0.0"},
      "resourceUri": "mcp://resource/chart-editor.html",
      "toolName": "chart-editor"
    }
  }' \
  http://localhost:8080/mcp | jq '.'

答复包括a sessionId 对于后续的UI调用：

{
  "result": {
    "sessionId": "abc123-...",
    "hostInfo": {"name": "camel-mcp", "version": "1.5.0"},
    "capabilities": ["tools/call", "ui/message", "ui/update-model-context"]
  }
}

ui/tools/call -从UI上下文执行工具

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ui-2",
    "method": "ui/tools/call",
    "params": {
      "sessionId": "",
      "name": "echo",
      "arguments": {"text": "Hello from UI!"}
    }
  }' \
  http://localhost:8080/mcp | jq '.'

ui/message -从嵌入式UI发送消息

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ui-3",
    "method": "ui/message",
    "params": {
      "sessionId": "",
      "type": "user-action",
      "payload": {"action": "button-clicked"}
    }
  }' \
  http://localhost:8080/mcp | jq '.'

ui/update-model-context -更新AI模型上下文

curl -s -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ui-4",
    "method": "ui/update-model-context",
    "params": {
      "sessionId": "",
      "context": {"chartConfig": {"type": "bar", "data": [1,2,3]}},
      "mode": "merge"
    }
  }' \
  http://localhost:8080/mcp | jq '.'

通过WebSocket调用MCP方法

npx wscat -c ws://localhost:8090/mcp

# Initialize
> {"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"ws-client","version":"1.0.0"}}}

# Ping
> {"jsonrpc":"2.0","id":"2","method":"ping"}

# List tools
> {"jsonrpc":"2.0","id":"3","method":"tools/list"}

# Call a tool
> {"jsonrpc":"2.0","id":"4","method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello"}}}

# Get a resource
> {"jsonrpc":"2.0","id":"5","method":"resources/get","params":{"resource":"example-resource"}}

最小YAML客户端（骆驼路线）

- route:
    id: example-mcp-client
    from:
      uri: "timer://runOnce?repeatCount=1"
      steps:
        - setBody:
            constant: |
              {
                "method": "initialize",
                "params": {
                  "clientInfo": {
                    "name": "camel-mcp",
                    "version": "1.0.0"
                  }
                }
              }
        - unmarshal:
            json:
              library: Jackson
        - to:
            uri: "mcp:http://localhost:8080/mcp?method=initialize"
        - log:
            message: "MCP Response: ${body}"

资源/获取样品服务

这 resources/get 方法支持自动内容类型检测：

• 二进制 （图片、PDF、字体）→ 以base64返回 blob
• 文本 （html、css、js、md）→ 返回为 text MIME类型
• JSON （无延期）→ 作为结构化数据返回

- route:
    id: example-resources-client
    from:
      uri: "timer://resources?repeatCount=1"
      steps:
        - setBody:
            constant: |
              {
                "params": {
                  "resource": "example-resource"
                }
              }
        - unmarshal:
            json:
              library: Jackson
        - to:
            uri: "mcp:http://localhost:8080/mcp?method=resources/get"
        - log:
            message: "Resource payload: ${body[result]}"

MCP服务器（消费者）示例

MCP消费者允许您创建监听传入JSON-RPC请求的MCP协议服务器。

基本HTTP服务器

from("mcp:http://localhost:8080/mcp")
    .process(exchange -> {
        // Your custom MCP request processing
        String method = exchange.getProperty("mcp.jsonrpc.method", String.class);
        Map params = exchange.getIn().getBody(Map.class);
        
        // Process request and set response
        Map response = Map.of(
            "jsonrpc", "2.0",
            "id", exchange.getProperty("mcp.jsonrpc.id"),
            "result", Map.of("status", "ok")
        );
        exchange.getMessage().setBody(response);
    });

WebSocket服务器

from("mcp:http://localhost:8090/mcp?websocket=true")
    .process(exchange -> {
        // Process MCP requests over WebSocket
        // Response automatically serialized to JSON
    });

基于YAML的服务器

- route:
    id: mcp-server
    from:
      uri: "mcp:http://0.0.0.0:8080/mcp"
      steps:
        - choice:
            when:
              - simple: "${exchangeProperty.mcp.jsonrpc.method} == 'ping'"
                steps:
                  - setBody:
                      constant:
                        jsonrpc: "2.0"
                        result: {}
              - simple: "${exchangeProperty.mcp.jsonrpc.method} == 'tools/list'"
                steps:
                  - setBody:
                      constant:
                        jsonrpc: "2.0"
                        result:
                          tools:
                            - name: "echo"
                              description: "Echo the input"

消费者自动：

• 验证HTTP标头（内容类型、接受）
• 解析JSON-RPC信封
• 提取方法和参数作为交换属性
• 应用速率限制和请求大小保护
• 将响应体序列化为JSON

🤖 MCP工具

• AbstractMcpRequestProcessor 和 AbstractMcpResponseProcessor 为自定义工具处理程序提供模板。
• McpResourcesGetProcessor 使用自动内容类型检测和辅助方法处理资源加载：

- isBinaryResource(name) / isTextResource(name) --检查内容类型 - getMimeType(name) --从扩展名解析MIME类型 - blobResource(uri, mimeType, bytes) --创建二进制响应 - textResource(uri, mimeType, content) --创建文本响应 - jsonResource(uri, data) --创建JSON响应

• McpNotificationProcessor 规范JSON-RPC通知和交换属性。
• 工具目录从以下位置加载 classpath:mcp/methods.yaml 和饲料 tools/list 自动响应。

🧪 测试

mvn clean install

集成测试启动中定义的模拟MCP服务器 src/test/resources/routes 通过Camel Main。

🧰 样品

mcp服务（Kamelet/YAML路由）

功能齐全的MCP服务器，具有基于Kamelet的路由、UI桥、资源目录和OpenAPI生成。

mvn -f samples/mcp-service/pom.xml exec:java
# HTTP: http://localhost:8080/mcp  |  WebSocket: ws://localhost:8090/mcp

mcp消费者（直接消费者URI）

最小MCP服务器演示 from("mcp:...") 消费者方法——纯Java，不需要YAML。

mvn -f samples/mcp-consumer/pom.xml exec:java
# HTTP: http://localhost:3000/mcp  |  WebSocket: ws://localhost:3001/mcp

看 示例/mcp消费者/README.md 了解细节和卷曲示例。

核心部件烟雾测试

mvn exec:java -Dexec.mainClass=org.apache.camel.main.Main

运行示例时，您可以练习MCP HTTP端点：

# JSON resource (no extension)
curl -s -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"resources/get","params":{"resource":"example-resource"}}' \
  http://localhost:8080/mcp

# HTML resource
curl -s -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"2","method":"resources/get","params":{"resource":"sample.html"}}' \
  http://localhost:8080/mcp

# Binary image resource
curl -s -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"3","method":"resources/get","params":{"resource":"sample-image.jpg"}}' \
  http://localhost:8080/mcp

HTTP端点侦听 http://localhost:8080；WebSocket帮助程序可在 ws://localhost:8090/mcp生成的OpenAPI定义位于 samples/mcp-service/target/openapi/。邮递员的藏品被捆绑在 samples/mcp-service/postman/ 用于互动探索。

🔌 IDE和工具集成

骆驼组件描述符

该构建在以下位置生成了一个标准的Camel组件描述符 src/generated/resources/META-INF/io/dscope/camel/mcp/mcp.json这使得：

• IDE自动补全 mcp: YAML/Java路由中的URI
• 文档中自动生成的选项表
• 通过以下方式进行财产验证 McpEndpointConfigurer 和 McpComponentConfigurer

其他Camel标准属性会自动显示： bridgeErrorHandler, lazyStartProducer, exceptionHandler, exchangePattern, autowiredEnabled.

Apache Karavan集成

为生成可视化设计器元数据 阿帕奇卡拉万:

mvn -Pkaravan-metadata compile exec:java

这将在以下情况下生成元数据 src/main/resources/karavan/metadata/:

添加新的MCP方法或更改组件属性后重新生成。

🧱 项目布局

io.dscope.camel.mcp/
├── McpComponent        # Camel component entry point
├── McpEndpoint         # Holds configuration, creates producer/consumer (@UriEndpoint, Category.AI)
├── McpConfiguration    # URI path/param bindings with Camel annotations
├── McpProducer         # Sends MCP JSON-RPC requests to remote servers (client mode)
├── McpConsumer         # Receives MCP requests via HTTP/WebSocket (server mode)
├── processor/          # 20+ built-in processors for JSON-RPC, tools, resources, UI, notifications
├── catalog/            # McpMethodCatalog + McpResourceCatalog (loaded from YAML)
├── service/            # McpUiSessionRegistry, McpWebSocketNotifier
├── model/              # Jackson POJOs: requests, responses, resources, UI sessions, notifications
└── tools/karavan/      # McpKaravanMetadataGenerator for Karavan visual designer

samples/
├── mcp-service/        # Full-featured MCP server using Kamelets/YAML routes (port 8080/8090)
└── mcp-consumer/       # Minimal MCP server using direct consumer URI (port 3000/3001)

src/generated/          # Auto-generated component descriptors (mcp.json, configurers, URI factory)
src/main/resources/karavan/metadata/  # Generated Karavan metadata (component, kamelets, labels)
src/main/docs/mcp-component.adoc      # AsciiDoc component documentation for Camel tooling

📄 许可证

根据Apache许可证2.0授权。看 LICENSE 全文。