# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个基于 Model Context Protocol (MCP) 的 DeepSeek API 服务器，允许通过 MCP 协议与 DeepSeek 模型进行交互。

## 核心构建命令

### 基本构建
```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务器（生产模式）
npm start

# 开发模式（热重载）
npm run dev
```

### 测试和验证
```bash
# 运行自动化测试
node test.mjs

# 使用自动安装脚本
./setup.sh
```

## 项目架构

### 模块结构
- **src/index.ts** - MCP 服务器主入口，注册工具和处理请求
- **src/deepseek-client.ts** - DeepSeek API 客户端，处理与 DeepSeek API 的通信
- **src/types.ts** - TypeScript 类型定义，包含所有 API 请求和响应类型

### 核心组件
1. **DeepSeekMCPServer** - 主服务器类，继承 MCP SDK 并注册工具
2. **DeepSeekClient** - API 客户端类，处理 HTTP 请求和认证
3. **工具注册系统** - 自动注册四个主要工具：chat、list_models、get_balance、stream_chat

### 技术栈
- **运行时**: Node.js + TypeScript
- **协议**: Model Context Protocol (MCP) SDK
- **HTTP 客户端**: 原生 fetch API
- **参数验证**: Zod
- **环境变量**: dotenv

## 开发环境要求

### 系统要求
- Node.js >= 18
- npm 或 yarn
- DeepSeek API 密钥

### 关键配置
- **目标环境**: ES2022
- **模块系统**: ES Modules
- **严格模式**: 启用 TypeScript 严格模式
- **输出目录**: ./dist

## 环境变量配置

必须设置以下环境变量：
```bash
DEEPSEEK_API_KEY=your_deepseek_api_key_here
```

可以通过 `.env` 文件或系统环境变量设置。

## 可用工具

### 1. chat - 聊天对话
与 DeepSeek 模型进行自然语言对话
- `message` (必需): 用户消息
- `model` (可选): 模型名称，默认为 "deepseek-chat"
- `temperature` (可选): 温度参数 (0-2)，默认为 0.7
- `maxTokens` (可选): 最大生成令牌数

### 2. list_models - 获取模型列表
获取 DeepSeek API 支持的所有模型列表

### 3. get_balance - 获取账户余额
查询 DeepSeek API 账户余额信息

### 4. stream_chat - 流式聊天对话
模拟流式对话功能（MCP 限制下使用非流式实现）

## 错误处理

服务器包含完整的错误处理机制：
- API 认证失败处理
- 网络连接错误处理
- 参数验证错误处理
- 服务器内部错误处理

## 部署配置

### 在 Claude Code 中使用
将服务器添加到 Claude Code 的 MCP 配置中：
```json
{
  "mcpServers": {
    "deepseek": {
      "command": "node",
      "args": ["/path/to/mcp-deepseek-server/dist/index.js"],
      "env": {
        "DEEPSEEK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## 关键依赖

### 核心依赖
- `@modelcontextprotocol/sdk` - MCP 协议 SDK
- `zod` - 参数验证
- `dotenv` - 环境变量加载

### 开发依赖
- `typescript` - TypeScript 编译器
- `tsx` - TypeScript 执行器
- `@types/node` - Node.js 类型定义

## 测试配置

项目包含完整的测试脚本 `test.mjs`，验证：
- 模型列表获取
- 账户余额查询
- 聊天对话功能

## 注意事项

1. **API 密钥安全**: 不要在代码中硬编码 API 密钥
2. **MCP 限制**: 由于 MCP 协议限制，stream_chat 工具实际上是模拟的
3. **错误处理**: 所有工具都包含完整的错误处理和用户友好的错误消息
4. **类型安全**: 使用 TypeScript 和 Zod 确保类型安全