> ## Documentation Index
> Fetch the complete documentation index at: https://startai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 面向客户端开发者
> 轻松打造专属客户端，无缝集成所有MCP服务器！
本教程将教您如何构建一个连接到MCP服务器的LLM驱动聊天机器人客户端。建议您先完成[服务器快速入门](/quickstart/server)，它会指导您构建第一个服务器的基础知识。
[您可以在这里找到本教程的完整代码。](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-python)
### 系统要求
开始前，请确保您的系统满足以下要求：
* Mac或Windows电脑
* 安装最新版Python
* 安装最新版`uv`
### 设置环境
首先，使用`uv`创建一个新的Python项目：
```bash theme={null}
# 创建项目目录
uv init mcp-client
cd mcp-client
# 创建虚拟环境
uv venv
# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Unix或MacOS:
source .venv/bin/activate
# 安装所需包
uv add mcp anthropic python-dotenv
# 删除样板文件
rm main.py
# 创建主文件
touch client.py
```
### 设置API密钥
您需要从[Anthropic控制台](https://console.anthropic.com/settings/keys)获取Anthropic API密钥。
创建`.env`文件来存储它：
```bash theme={null}
# 创建.env文件
touch .env
```
将密钥添加到`.env`文件中：
```bash theme={null}
ANTHROPIC_API_KEY=<您的密钥>
```
将`.env`添加到`.gitignore`：
```bash theme={null}
echo ".env" >> .gitignore
```
### 创建客户端
#### 基本客户端结构
首先，设置导入并创建基本客户端类：
```python theme={null}
import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv() # 从.env加载环境变量
class MCPClient:
def __init__(self):
# 初始化会话和客户端对象
self.session: Optional[ClientSession] = None
self.exit_stack = AsyncExitStack()
self.anthropic = Anthropic()
# 方法将在这里添加
```
#### 服务器连接管理
接下来，实现连接到MCP服务器的方法：
```python theme={null}
async def connect_to_server(self, server_script_path: str):
"""连接到MCP服务器
参数:
server_script_path: 服务器脚本路径(.py或.js)
"""
is_python = server_script_path.endswith('.py')
is_js = server_script_path.endswith('.js')
if not (is_python or is_js):
raise ValueError("服务器脚本必须是.py或.js文件")
command = "python" if is_python else "node"
server_params = StdioServerParameters(
command=command,
args=[server_script_path],
env=None
)
stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
self.stdio, self.write = stdio_transport
self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
await self.session.initialize()
# 列出可用工具
response = await self.session.list_tools()
tools = response.tools
print("\n已连接到服务器，可用工具:", [tool.name for tool in tools])
```
#### 查询处理逻辑
现在添加处理查询和处理工具调用的核心功能：
```python theme={null}
async def process_query(self, query: str) -> str:
"""使用Claude和可用工具处理查询"""
messages = [
{
"role": "user",
"content": query
}
]
response = await self.session.list_tools()
available_tools = [{
"name": tool.name,
"description": tool.description,
"input_schema": tool.inputSchema
} for tool in response.tools]
# 初始Claude API调用
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
# 处理响应和工具调用
final_text = []
assistant_message_content = []
for content in response.content:
if content.type == 'text':
final_text.append(content.text)
assistant_message_content.append(content)
elif content.type == 'tool_use':
tool_name = content.name
tool_args = content.input
# 执行工具调用
result = await self.session.call_tool(tool_name, tool_args)
final_text.append(f"[正在调用工具 {tool_name}，参数 {tool_args}]")
assistant_message_content.append(content)
messages.append({
"role": "assistant",
"content": assistant_message_content
})
messages.append({
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": content.id,
"content": result.content
}
]
})
# 从Claude获取下一个响应
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
final_text.append(response.content[0].text)
return "\n".join(final_text)
```
#### 交互式聊天界面
现在添加聊天循环和清理功能：
```python theme={null}
async def chat_loop(self):
"""运行交互式聊天循环"""
print("\nMCP客户端已启动！")
print("输入您的查询或输入'quit'退出。")
while True:
try:
query = input("\n查询: ").strip()
if query.lower() == 'quit':
break
response = await self.process_query(query)
print("\n" + response)
except Exception as e:
print(f"\n错误: {str(e)}")
async def cleanup(self):
"""清理资源"""
await self.exit_stack.aclose()
```
#### 主入口点
最后，添加主执行逻辑：
```python theme={null}
async def main():
if len(sys.argv) < 2:
print("用法: python client.py <服务器脚本路径>")
sys.exit(1)
client = MCPClient()
try:
await client.connect_to_server(sys.argv[1])
await client.chat_loop()
finally:
await client.cleanup()
if __name__ == "__main__":
import sys
asyncio.run(main())
```
### 关键组件说明
#### 1. 客户端初始化
* `MCPClient`类使用会话管理和API客户端进行初始化
* 使用`AsyncExitStack`进行资源管理
* 配置Anthropic客户端用于Claude交互
#### 2. 服务器连接
* 支持Python和Node.js服务器
* 验证服务器脚本类型
* 设置通信通道
* 初始化会话并列出可用工具
#### 3. 查询处理
* 维护对话上下文
* 处理Claude的响应和工具调用
* 管理Claude和工具之间的消息流
* 将结果组合成连贯的响应
#### 4. 交互式界面
* 提供简单的命令行界面
* 处理用户输入并显示响应
* 包含基本错误处理
* 允许优雅退出
#### 5. 资源管理
* 资源的适当清理
* 连接问题的错误处理
* 优雅关闭程序
### 常见自定义点
1. **工具处理**
* 修改`process_query()`以处理特定工具类型
* 为工具调用添加自定义错误处理
* 实现工具特定的响应格式化
2. **响应处理**
* 自定义工具结果格式
* 添加响应过滤或转换
* 实现自定义日志记录
3. **用户界面**
* 添加GUI或Web界面
* 实现丰富的控制台输出
* 添加命令历史记录或自动补全
### 运行客户端
要使用任何MCP服务器运行您的客户端：
```bash theme={null}
uv run client.py 服务器脚本路径.py # python服务器
uv run client.py 服务器脚本路径.js # node服务器
```
客户端将：
1. 连接到指定的服务器
2. 列出可用工具
3. 开始交互式聊天会话，您可以：
* 输入查询
* 查看工具执行
* 获取来自Claude的响应
### 工作原理
当您提交查询时：
1. 客户端从服务器获取可用工具列表
2. 您的查询与工具描述一起发送给Claude
3. Claude决定使用哪些工具（如果有）
4. 客户端通过服务器执行请求的工具调用
5. 结果发送回Claude
6. Claude提供自然语言响应
7. 响应显示给您
### 最佳实践
1. **错误处理**
* 始终使用try-catch块包装工具调用
* 提供有意义的错误消息
* 优雅处理连接问题
2. **资源管理**
* 使用`AsyncExitStack`进行适当清理
* 使用完成后关闭连接
* 处理服务器断开连接
3. **安全性**
* 在`.env`中安全存储API密钥
* 验证服务器响应
* 谨慎处理工具权限
### 故障排除
#### 服务器路径问题
* 仔细检查服务器脚本路径是否正确
* 如果相对路径不起作用，请使用绝对路径
* Windows用户，确保在路径中使用正斜杠(/)或转义反斜杠(\\)
* 验证服务器文件拥有正确的扩展名(.py用于Python或.js用于Node.js)
正确路径用法示例：
```bash theme={null}
# 相对路径
uv run client.py ./server/weather.py
# 绝对路径
uv run client.py /Users/username/projects/mcp-server/weather.py
# Windows路径（两种格式都可用）
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py
```
#### 响应时间
* 第一个响应可能需要30秒才能返回
* 这是正常现象，发生在：
* 服务器初始化
* Claude处理查询
* 工具执行期间
* 后续响应通常更快
* 在初始等待期间不要中断进程
#### 常见错误消息
如果您看到：
* `FileNotFoundError`：检查服务器路径
* `Connection refused`：确保服务器正在运行且路径正确
* `Tool execution failed`：验证工具所需的环境变量已设置
* `Timeout error`：考虑在客户端配置中增加超时时间
[您可以在这里找到本教程的完整代码。](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-typescript)
## 系统要求
开始前，请确保您的系统满足以下要求：
* Mac或Windows电脑
* 安装Node.js 17或更高版本
* 安装最新版本的`npm`
* Anthropic API密钥(Claude)
## 设置您的环境
首先，让我们创建并设置我们的项目：
```bash MacOS/Linux theme={null}
# 创建项目目录
mkdir mcp-client-typescript
cd mcp-client-typescript
# 初始化npm项目
npm init -y
# 安装依赖
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
# 安装开发依赖
npm install -D @types/node typescript
# 创建源文件
touch index.ts
```
```powershell Windows theme={null}
# 创建项目目录
md mcp-client-typescript
cd mcp-client-typescript
# 初始化npm项目
npm init -y
# 安装依赖
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
# 安装开发依赖
npm install -D @types/node typescript
# 创建源文件
new-item index.ts
```
更新您的`package.json`以设置`type: "module"`和构建脚本：
```json package.json theme={null}
{
"type": "module",
"scripts": {
"build": "tsc && chmod 755 build/index.js"
}
}
```
在项目根目录创建一个`tsconfig.json`：
```json tsconfig.json theme={null}
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["index.ts"],
"exclude": ["node_modules"]
}
```
## 设置您的API密钥
您需要从[Anthropic控制台](https://console.anthropic.com/settings/keys)获取Anthropic API密钥。
创建一个`.env`文件来存储它：
```bash theme={null}
echo "ANTHROPIC_API_KEY=<您的密钥>" > .env
```
将`.env`添加到您的`.gitignore`：
```bash theme={null}
echo ".env" >> .gitignore
```
确保您的`ANTHROPIC_API_KEY`安全！
## 创建客户端
### 基本客户端结构
首先，让我们在`index.ts`中设置导入并创建基本客户端类：
```typescript theme={null}
import { Anthropic } from "@anthropic-ai/sdk";
import {
MessageParam,
Tool,
} from "@anthropic-ai/sdk/resources/messages/messages.mjs";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import readline from "readline/promises";
import dotenv from "dotenv";
dotenv.config();
const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (!ANTHROPIC_API_KEY) {
throw new Error("ANTHROPIC_API_KEY未设置");
}
class MCPClient {
private mcp: Client;
private anthropic: Anthropic;
private transport: StdioClientTransport | null = null;
private tools: Tool[] = [];
constructor() {
this.anthropic = new Anthropic({
apiKey: ANTHROPIC_API_KEY,
});
this.mcp = new Client({ name: "mcp-client-cli", version: "1.0.0" });
}
// 方法将在这里添加
}
```
### 服务器连接管理
接下来，我们将实现连接到MCP服务器的方法：
```typescript theme={null}
async connectToServer(serverScriptPath: string) {
try {
const isJs = serverScriptPath.endsWith(".js");
const isPy = serverScriptPath.endsWith(".py");
if (!isJs && !isPy) {
throw new Error("服务器脚本必须是.js或.py文件");
}
const command = isPy
? process.platform === "win32"
? "python"
: "python3"
: process.execPath;
this.transport = new StdioClientTransport({
command,
args: [serverScriptPath],
});
this.mcp.connect(this.transport);
const toolsResult = await this.mcp.listTools();
this.tools = toolsResult.tools.map((tool) => {
return {
name: tool.name,
description: tool.description,
input_schema: tool.inputSchema,
};
});
console.log(
"已连接到服务器，可用工具:",
this.tools.map(({ name }) => name)
);
} catch (e) {
console.log("连接到MCP服务器失败: ", e);
throw e;
}
}
```
### 查询处理逻辑
现在让我们添加处理查询和处理工具调用的核心功能：
```typescript theme={null}
async processQuery(query: string) {
const messages: MessageParam[] = [
{
role: "user",
content: query,
},
];
const response = await this.anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1000,
messages,
tools: this.tools,
});
const finalText = [];
const toolResults = [];
for (const content of response.content) {
if (content.type === "text") {
finalText.push(content.text);
} else if (content.type === "tool_use") {
const toolName = content.name;
const toolArgs = content.input as { [x: string]: unknown } | undefined;
const result = await this.mcp.callTool({
name: toolName,
arguments: toolArgs,
});
toolResults.push(result);
finalText.push(
`[正在调用工具 ${toolName}，参数 ${JSON.stringify(toolArgs)}]`
);
messages.push({
role: "user",
content: result.content as string,
});
const response = await this.anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1000,
messages,
});
finalText.push(
response.content[0].type === "text" ? response.content[0].text : ""
);
}
}
return finalText.join("\n");
}
```
### 交互式聊天界面
现在我们将添加聊天循环和清理功能：
```typescript theme={null}
async chatLoop() {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
try {
console.log("\nMCP客户端已启动！");
console.log("输入您的查询或输入'quit'退出。");
while (true) {
const message = await rl.question("\n查询: ");
if (message.toLowerCase() === "quit") {
break;
}
const response = await this.processQuery(message);
console.log("\n" + response);
}
} finally {
rl.close();
}
}
async cleanup() {
await this.mcp.close();
}
```
### 主入口点
最后，我们将添加主执行逻辑：
```typescript theme={null}
async function main() {
if (process.argv.length < 3) {
console.log("用法: node index.ts <服务器脚本路径>");
return;
}
const mcpClient = new MCPClient();
try {
await mcpClient.connectToServer(process.argv[2]);
await mcpClient.chatLoop();
} finally {
await mcpClient.cleanup();
process.exit(0);
}
}
main();
```
## 运行客户端
要使用任何MCP服务器运行您的客户端：
```bash theme={null}
# 构建TypeScript
npm run build
# 运行客户端
node build/index.js 路径/到/服务器.py # python服务器
node build/index.js 路径/到/build/index.js # node服务器
```
如果您继续使用服务器快速入门中的天气教程，您的命令可能看起来像这样：`node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`
**客户端将：**
1. 连接到指定的服务器
2. 列出可用工具
3. 开始交互式聊天会话，您可以：
* 输入查询
* 查看工具执行
* 获取来自Claude的响应
## 工作原理
当您提交查询时：
1. 客户端从服务器获取可用工具列表
2. 您的查询连同工具描述一起发送给Claude
3. Claude决定使用哪些工具（如果有）
4. 客户端通过服务器执行任何请求的工具调用
5. 结果发送回Claude
6. Claude提供自然语言响应
7. 响应显示给您
## 最佳实践
1. **错误处理**
* 使用TypeScript的类型系统实现更好的错误检测
* 在try-catch块中包装工具调用
* 提供有意义的错误消息
* 优雅处理连接问题
2. **安全性**
* 在`.env`中安全存储API密钥
* 验证服务器响应
* 对工具权限保持谨慎
## 故障排除
### 服务器路径问题
* 仔细检查服务器脚本路径是否正确
* 如果相对路径不起作用，请使用绝对路径
* 对于Windows用户，确保在路径中使用正斜杠(/)或转义反斜杠(\\)
* 验证服务器文件具有正确的扩展名(.js用于Node.js或.py用于Python)
正确路径用法示例：
```bash theme={null}
# 相对路径
node build/index.js ./server/build/index.js
# 绝对路径
node build/index.js /Users/username/projects/mcp-server/build/index.js
# Windows路径（两种格式都可用）
node build/index.js C:/projects/mcp-server/build/index.js
node build/index.js C:\\projects\\mcp-server\\build\\index.js
```
### 响应时间
* 第一个响应可能需要30秒才能返回
* 这是正常现象，发生在：
* 服务器初始化
* Claude处理查询
* 工具执行期间
* 后续响应通常更快
* 在初始等待期间不要中断进程
### 常见错误消息
如果您看到：
* `Error: Cannot find module`：检查您的构建文件夹并确保TypeScript编译成功
* `Connection refused`：确保服务器正在运行且路径正确
* `Tool execution failed`：验证工具所需的环境变量已设置
* `ANTHROPIC_API_KEY未设置`：检查您的.env文件和环境变量
* `TypeError`：确保您为工具参数使用了正确的类型
这是一个基于Spring AI MCP自动配置和启动器的快速入门演示。
要了解如何手动创建同步和异步MCP客户端，请参阅[Java SDK客户端](/sdk/java/mcp-client)文档
本示例演示如何构建一个交互式聊天机器人，它结合了Spring AI的模型上下文协议(MCP)和[Brave Search MCP服务器](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)。该应用程序创建了一个由Anthropic的Claude AI模型驱动的会话界面，可以通过Brave Search执行互联网搜索，从而实现与实时网络数据的自然语言交互。
[您可以在这里找到本教程的完整代码。](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)
## 系统要求
开始前，请确保您的系统满足以下要求：
* Java 17或更高版本
* Maven 3.6+
* npx包管理器
* Anthropic API密钥(Claude)
* Brave Search API密钥
## 设置您的环境
1. 安装npx(Node Package eXecute)：
首先，确保安装[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
然后运行：
```bash theme={null}
npm install -g npx
```
2. 克隆仓库：
```bash theme={null}
git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave-chatbot
```
3. 设置您的API密钥：
```bash theme={null}
export ANTHROPIC_API_KEY='您的anthropic-api-密钥'
export BRAVE_API_KEY='您的brave-api-密钥'
```
4. 构建应用程序：
```bash theme={null}
./mvnw clean install
```
5. 使用Maven运行应用程序：
```bash theme={null}
./mvnw spring-boot:run
```
确保您的`ANTHROPIC_API_KEY`和`BRAVE_API_KEY`密钥安全！
## 工作原理
该应用程序通过几个组件将Spring AI与Brave Search MCP服务器集成：
### MCP客户端配置
1. pom.xml中所需的依赖项：
```xml theme={null}
org.springframework.ai
spring-ai-starter-mcp-client
org.springframework.ai
spring-ai-starter-model-anthropic
```
2. 应用程序属性(application.yml)：
```yml theme={null}
spring:
ai:
mcp:
client:
enabled: true
name: brave-search-client
version: 1.0.0
type: SYNC
request-timeout: 20s
stdio:
root-change-notification: true
servers-configuration: classpath:/mcp-servers-config.json
toolcallback:
enabled: true
anthropic:
api-key: ${ANTHROPIC_API_KEY}
```
这激活了`spring-ai-starter-mcp-client`，根据提供的服务器配置创建一个或多个`McpClient`。
`spring.ai.mcp.client.toolcallback.enabled=true`属性启用了工具回调机制，自动将所有MCP工具注册为spring ai工具。
该功能默认是禁用的。
3. MCP服务器配置(`mcp-servers-config.json`)：
```json theme={null}
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-brave-search"
],
"env": {
"BRAVE_API_KEY": "<放置您的BRAVE API密钥>"
}
}
}
}
```
### 聊天实现
聊天机器人使用Spring AI的ChatClient与MCP工具集成实现：
```java theme={null}
var chatClient = chatClientBuilder
.defaultSystem("You are useful assistant, expert in AI and Java.")
.defaultTools((Object[]) mcpToolAdapter.toolCallbacks())
.defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
.build();
```
主要特点：
* 使用Claude AI模型进行自然语言理解
* 通过MCP集成Brave Search实现实时网络搜索能力
* 使用InMemoryChatMemory维护对话记忆
* 作为交互式命令行应用程序运行
### 构建和运行
```bash theme={null}
./mvnw clean install
java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
```
或者
```bash theme={null}
./mvnw spring-boot:run
```
应用程序将启动一个交互式聊天会话，您可以在其中提问。当聊天机器人需要从互联网查找信息来回答您的问题时，它将使用Brave Search。
聊天机器人可以：
* 使用其内置知识回答问题
* 在需要时使用Brave Search执行网络搜索
* 记住对话中的上下文
* 从多个来源结合信息提供全面的答案
### 高级配置
MCP客户端支持额外的配置选项：
* 通过`McpSyncClientCustomizer`或`McpAsyncClientCustomizer`自定义客户端
* 多客户端与多种传输类型：`STDIO`和`SSE`(服务器发送事件)
* 与Spring AI的工具执行框架集成
* 自动客户端初始化和生命周期管理
对于基于WebFlux的应用程序，您可以使用WebFlux启动器：
```xml theme={null}
org.springframework.ai
spring-ai-mcp-client-webflux-spring-boot-starter
```
这提供了类似的功能，但使用基于WebFlux的SSE传输实现，推荐用于生产部署。
[您可以在这里找到本教程的完整代码。](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-client)
## 系统要求
开始前，请确保您的系统满足以下要求：
* Java 17或更高版本
* Anthropic API密钥(Claude)
## 设置您的环境
首先，如果您尚未安装`java`和`gradle`，请先安装它们。
您可以从[Oracle JDK官方网站](https://www.oracle.com/java/technologies/downloads/)下载`java`。
验证您的`java`安装：
```bash theme={null}
java --version
```
现在，让我们创建并设置您的项目：
```bash MacOS/Linux theme={null}
# 为我们的项目创建一个新目录
mkdir kotlin-mcp-client
cd kotlin-mcp-client
# 初始化一个新的kotlin项目
gradle init
```
```powershell Windows theme={null}
# 为我们的项目创建一个新目录
md kotlin-mcp-client
cd kotlin-mcp-client
# 初始化一个新的kotlin项目
gradle init
```
运行`gradle init`后，您将看到创建项目的选项。
选择**Application**作为项目类型，**Kotlin**作为编程语言，以及**Java 17**作为Java版本。
或者，您可以使用[IntelliJ IDEA项目向导](https://kotlinlang.org/docs/jvm-get-started.html)创建Kotlin应用程序。
创建项目后，添加以下依赖项：
```kotlin build.gradle.kts theme={null}
val mcpVersion = "0.4.0"
val slf4jVersion = "2.0.9"
val anthropicVersion = "0.8.0"
dependencies {
implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
implementation("org.slf4j:slf4j-nop:$slf4jVersion")
implementation("com.anthropic:anthropic-java:$anthropicVersion")
}
```
```groovy build.gradle theme={null}
def mcpVersion = '0.3.0'
def slf4jVersion = '2.0.9'
def anthropicVersion = '0.8.0'
dependencies {
implementation "io.modelcontextprotocol:kotlin-sdk:$mcpVersion"
implementation "org.slf4j:slf4j-nop:$slf4jVersion"
implementation "com.anthropic:anthropic-java:$anthropicVersion"
}
```
还需要在构建脚本中添加以下插件：
```kotlin build.gradle.kts theme={null}
plugins {
id("com.github.johnrengelman.shadow") version "8.1.1"
}
```
```groovy build.gradle theme={null}
plugins {
id 'com.github.johnrengelman.shadow' version '8.1.1'
}
```
## 设置您的API密钥
您需要从[Anthropic控制台](https://console.anthropic.com/settings/keys)获取Anthropic API密钥。
设置您的API密钥：
```bash theme={null}
export ANTHROPIC_API_KEY='您的anthropic-api-密钥'
```
确保您的`ANTHROPIC_API_KEY`安全！
## 创建客户端
### 基本客户端结构
首先，让我们创建基本的客户端类：
```kotlin theme={null}
class MCPClient : AutoCloseable {
private val anthropic = AnthropicOkHttpClient.fromEnv()
private val mcp: Client = Client(clientInfo = Implementation(name = "mcp-client-cli", version = "1.0.0"))
private lateinit var tools: List
// 方法将在这里添加
override fun close() {
runBlocking {
mcp.close()
anthropic.close()
}
}
```
### 服务器连接管理
接下来，我们将实现连接到MCP服务器的方法：
```kotlin theme={null}
suspend fun connectToServer(serverScriptPath: String) {
try {
val command = buildList {
when (serverScriptPath.substringAfterLast(".")) {
"js" -> add("node")
"py" -> add(if (System.getProperty("os.name").lowercase().contains("win")) "python" else "python3")
"jar" -> addAll(listOf("java", "-jar"))
else -> throw IllegalArgumentException("服务器脚本必须是.js、.py或.jar文件")
}
add(serverScriptPath)
}
val process = ProcessBuilder(command).start()
val transport = StdioClientTransport(
input = process.inputStream.asSource().buffered(),
output = process.outputStream.asSink().buffered()
)
mcp.connect(transport)
val toolsResult = mcp.listTools()
tools = toolsResult?.tools?.map { tool ->
ToolUnion.ofTool(
Tool.builder()
.name(tool.name)
.description(tool.description ?: "")
.inputSchema(
Tool.InputSchema.builder()
.type(JsonValue.from(tool.inputSchema.type))
.properties(tool.inputSchema.properties.toJsonValue())
.putAdditionalProperty("required", JsonValue.from(tool.inputSchema.required))
.build()
)
.build()
)
} ?: emptyList()
println("已连接到服务器，可用工具: ${tools.joinToString(", ") { it.tool().get().name() }}")
} catch (e: Exception) {
println("连接到MCP服务器失败: $e")
throw e
}
}
```
还需要创建一个辅助函数，将`JsonObject`转换为Anthropic使用的`JsonValue`：
```kotlin theme={null}
private fun JsonObject.toJsonValue(): JsonValue {
val mapper = ObjectMapper()
val node = mapper.readTree(this.toString())
return JsonValue.fromJsonNode(node)
}
```
### 查询处理逻辑
现在让我们添加处理查询和处理工具调用的核心功能：
```kotlin theme={null}
private val messageParamsBuilder: MessageCreateParams.Builder = MessageCreateParams.builder()
.model(Model.CLAUDE_3_5_SONNET_20241022)
.maxTokens(1024)
suspend fun processQuery(query: String): String {
val messages = mutableListOf(
MessageParam.builder()
.role(MessageParam.Role.USER)
.content(query)
.build()
)
val response = anthropic.messages().create(
messageParamsBuilder
.messages(messages)
.tools(tools)
.build()
)
val finalText = mutableListOf()
response.content().forEach { content ->
when {
content.isText() -> finalText.add(content.text().getOrNull()?.text() ?: "")
content.isToolUse() -> {
val toolName = content.toolUse().get().name()
val toolArgs =
content.toolUse().get()._input().convert(object : TypeReference>() {})
val result = mcp.callTool(
name = toolName,
arguments = toolArgs ?: emptyMap()
)
finalText.add("[正在调用工具 $toolName，参数 $toolArgs]")
messages.add(
MessageParam.builder()
.role(MessageParam.Role.USER)
.content(
"""
"type": "tool_result",
"tool_name": $toolName,
"result": ${result?.content?.joinToString("\n") { (it as TextContent).text ?: "" }}
""".trimIndent()
)
.build()
)
val aiResponse = anthropic.messages().create(
messageParamsBuilder
.messages(messages)
.build()
)
finalText.add(aiResponse.content().first().text().getOrNull()?.text() ?: "")
}
}
}
return finalText.joinToString("\n", prefix = "", postfix = "")
}
```
### 交互式聊天
我们将添加聊天循环：
```kotlin theme={null}
suspend fun chatLoop() {
println("\nMCP客户端已启动！")
println("输入您的查询或输入'quit'退出。")
while (true) {
print("\n查询: ")
val message = readLine() ?: break
if (message.lowercase() == "quit") break
val response = processQuery(message)
println("\n$response")
}
}
```
### 主入口点
最后，我们将添加主执行函数：
```kotlin theme={null}
fun main(args: Array) = runBlocking {
if (args.isEmpty()) throw IllegalArgumentException("用法: java -jar <您的路径>/build/libs/kotlin-mcp-client-0.1.0-all.jar <服务器脚本路径>")
val serverPath = args.first()
val client = MCPClient()
client.use {
client.connectToServer(serverPath)
client.chatLoop()
}
}
```
## 运行客户端
要使用任何MCP服务器运行您的客户端：
```bash theme={null}
./gradlew build
# 运行客户端
java -jar build/libs/<您的jar名称>.jar 路径/到/服务器.jar # jvm服务器
java -jar build/libs/<您的jar名称>.jar 路径/到/服务器.py # python服务器
java -jar build/libs/<您的jar名称>.jar 路径/到/build/index.js # node服务器
```
如果您继续使用服务器快速入门中的天气教程，您的命令可能看起来像这样：`java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar`
**客户端将：**
1. 连接到指定的服务器
2. 列出可用工具
3. 开始交互式聊天会话，您可以：
* 输入查询
* 查看工具执行
* 获取来自Claude的响应
## 工作原理
以下是高级工作流程示意图：
```mermaid theme={null}
---
config:
theme: neutral
---
sequenceDiagram
actor User
participant Client
participant Claude
participant MCP_Server as MCP Server
participant Tools
User->>Client: 发送查询
Client<<->>MCP_Server: 获取可用工具
Client->>Claude: 发送带有工具描述的查询
Claude-->>Client: 决定工具执行
Client->>MCP_Server: 请求执行工具
MCP_Server->>Tools: 执行选定的工具
Tools-->>MCP_Server: 返回结果
MCP_Server-->>Client: 发送结果
Client->>Claude: 发送工具结果
Claude-->>Client: 提供最终响应
Client-->>User: 显示响应
```
当您提交查询时：
1. 客户端从服务器获取可用工具列表
2. 您的查询连同工具描述一起发送给Claude
3. Claude决定使用哪些工具（如果有）
4. 客户端通过服务器执行任何请求的工具调用
5. 结果发送回Claude
6. Claude提供自然语言响应
7. 响应显示给您
## 最佳实践
1. **错误处理**
* 利用Kotlin的类型系统明确建模错误
* 当可能发生异常时，使用`try-catch`块包装外部工具和API调用
* 提供清晰明确的错误消息
* 优雅处理网络超时和连接问题
2. **安全性**
* 在`local.properties`、环境变量或密钥管理器中安全存储API密钥和机密
* 验证所有外部响应，避免使用意外或不安全的数据
* 在使用工具时谨慎对待权限和信任边界
## 故障排除
### 服务器路径问题
* 仔细检查服务器脚本路径是否正确
* 如果相对路径不起作用，请使用绝对路径
* 对于Windows用户，确保在路径中使用正斜杠(/)或转义反斜杠(\\)
* 确保已安装所需的运行时环境(Java用于Java，npm用于Node.js，或uv用于Python)
* 验证服务器文件具有正确的扩展名(.jar用于Java，.js用于Node.js或.py用于Python)
正确路径用法示例：
```bash theme={null}
# 相对路径
java -jar build/libs/client.jar ./server/build/libs/server.jar
# 绝对路径
java -jar build/libs/client.jar /Users/username/projects/mcp-server/build/libs/server.jar
# Windows路径（两种格式都可用）
java -jar build/libs/client.jar C:/projects/mcp-server/build/libs/server.jar
java -jar build/libs/client.jar C:\\projects\\mcp-server\\build\\libs\\server.jar
```
### 响应时间
* 第一个响应可能需要30秒才能返回
* 这是正常现象，发生在：
* 服务器初始化
* Claude处理查询
* 工具执行期间
* 后续响应通常更快
* 在初始等待期间不要中断进程
### 常见错误消息
如果您看到：
* `Connection refused`：确保服务器正在运行且路径正确
* `Tool execution failed`：验证工具所需的环境变量已设置
* `ANTHROPIC_API_KEY is not set`：检查您的环境变量
[您可以在这里找到本教程的完整代码。](https://github.io/modelcontextprotocol/csharp-sdk/tree/main/samples/QuickstartClient)
## 系统要求
开始前，请确保您的系统满足以下要求：
* .NET 8.0或更高版本
* Anthropic API密钥(Claude)
* Windows、Linux或MacOS
## 设置您的环境
首先，创建一个新的.NET项目：
```bash theme={null}
dotnet new console -n QuickstartClient
cd QuickstartClient
```
然后，向您的项目添加所需的依赖项：
```bash theme={null}
dotnet add package ModelContextProtocol --prerelease
dotnet add package Anthropic.SDK
dotnet add package Microsoft.Extensions.Hosting
```
## 设置您的API密钥
您需要从[Anthropic控制台](https://console.anthropic.com/settings/keys)获取Anthropic API密钥。
```bash theme={null}
dotnet user-secrets init
dotnet user-secrets set "ANTHROPIC_API_KEY" "<您的密钥>"
```
## 创建客户端
### 基本客户端结构
首先，让我们设置基本的客户端类：
```csharp theme={null}
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Configuration
.AddUserSecrets();
```
这创建了一个.NET控制台应用程序的基础，可以从用户机密中读取API密钥。
接下来，我们将设置MCP客户端：
```csharp theme={null}
var (command, arguments) = args switch
{
[var script] when script.EndsWith(".py") => ("python", script),
[var script] when script.EndsWith(".js") => ("node", script),
[var script] when Directory.Exists(script) || (File.Exists(script) && script.EndsWith(".csproj")) => ("dotnet", $"run --project {script} --no-build"),
_ => throw new NotSupportedException("提供了不支持的服务器脚本。支持的脚本有.py、.js或.csproj")
};
await using var mcpClient = await McpClientFactory.CreateAsync(new()
{
Id = "demo-server",
Name = "Demo Server",
TransportType = TransportTypes.StdIo,
TransportOptions = new()
{
["command"] = command,
["arguments"] = arguments,
}
});
var tools = await mcpClient.ListToolsAsync();
foreach (var tool in tools)
{
Console.WriteLine($"已连接到服务器，可用工具：{tool.Name}");
}
```
确保添加命名空间的`using`语句：
```csharp theme={null}
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;
```
这配置了一个MCP客户端，它将连接到作为命令行参数提供的服务器。然后它列出了连接服务器的可用工具。
### 查询处理逻辑
现在让我们添加处理查询和处理工具调用的核心功能：
```csharp theme={null}
using IChatClient anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
.Messages
.AsBuilder()
.UseFunctionInvocation()
.Build();
var options = new ChatOptions
{
MaxOutputTokens = 1000,
ModelId = "claude-3-5-sonnet-20241022",
Tools = [.. tools]
};
while (true)
{
Console.WriteLine("MCP客户端已启动！");
Console.WriteLine("输入您的查询或输入'quit'退出。");
string? query = Console.ReadLine();
if (string.IsNullOrWhiteSpace(query))
{
continue;
}
if (string.Equals(query, "quit", StringComparison.OrdinalIgnoreCase))
{
break;
}
var response = anthropicClient.GetStreamingResponseAsync(query, options);
await foreach (var message in response)
{
Console.Write(message.Text);
}
Console.WriteLine();
}
```
## 关键组件说明
### 1. 客户端初始化
* 客户端使用`McpClientFactory.CreateAsync()`初始化，该方法设置传输类型和运行服务器的命令。
### 2. 服务器连接
* 支持Python、Node.js和.NET服务器。
* 使用参数中指定的命令启动服务器。
* 配置使用stdio与服务器通信。
* 初始化会话和可用工具。
### 3. 查询处理
* 利用[Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-extensions)作为聊天客户端。
* 配置`IChatClient`使用自动工具(函数)调用。
* 客户端读取用户输入并发送到服务器。
* 服务器处理查询并返回响应。
* 向用户显示响应。
### 运行客户端
要使用任何MCP服务器运行您的客户端：
```bash theme={null}
dotnet run -- 路径/到/服务器.csproj # dotnet服务器
dotnet run -- 路径/到/服务器.py # python服务器
dotnet run -- 路径/到/服务器.js # node服务器
```
如果您继续使用服务器快速入门中的天气教程，您的命令可能看起来像这样：`dotnet run -- 路径/到/QuickstartWeatherServer`。
客户端将：
1. 连接到指定的服务器
2. 列出可用工具
3. 开始交互式聊天会话，您可以：
* 输入查询
* 查看工具执行
* 获取来自Claude的响应
4. 完成后退出会话
以下是连接到天气服务器快速入门时应该显示的样子：
## 下一步
查看我们的官方MCP服务器和实现库
查看支持MCP集成的客户端列表
了解如何使用像Claude这样的LLMs加速您的MCP开发
了解MCP如何连接客户端、服务器和LLMs