使用说明

演示MCP服务器

一个简单的演示 模型上下文协议（MCP） 服务器实现使用 JSON-RPC 2.0 通过HTTP。此演示服务器展示了如何使用两个图像处理示例工具实现MCP规范。

特性

JSON-RPC 2.0实现
使用标准方法支持MCP协议
两个示例工具：图像编码和场景生成
无API依赖性的模拟测试模式
基础档案管理和服务
调试日志

可用的MCP工具

1. `image_to_base64`

从URL下载图像并将其转换为保存在文件中的base64编码字符串。

输入参数：

url （string，必填）：要下载和编码的图像的URL

退货：

encodedFilePath：包含base64编码图像的文件的路径

用例： 为AI处理或存储准备图像

2. `img_scene_generator`

使用OpenAI的API基于文本提示和输入图像生成新图像。

输入参数：

prompt （字符串，必填）：场景生成的文本描述
encodedFilePath （string，必填）：带有base64编码图像的文件路径

退货：

situationDescription：AI生成的场景描述
image_url：访问生成图像的URL

用例： 基于现有图像创建AI生成的变体或场景

快速开始

先决条件

Python 3.8+
虚拟环境（推荐）
OpenAI API密钥（用于 img_scene_generator 工具）

1.安装

# Clone or download the project
cd demo-mcp-server

# Create and activate virtual environment
python -m venv myenv
source myenv/bin/activate  # On Windows: myenv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.配置

设置OpenAI API密钥（对于 img_scene_generator 工具）：

export OPENAI_API_KEY="your-actual-openai-api-key-here"

或者创建一个 .env 文件：

echo "OPENAI_API_KEY=your-actual-openai-api-key-here" > .env

3.运行服务器

真实模式（使用OpenAI API）：

python mcp_server.py

模拟模式（用于在没有API调用的情况下进行测试）：

python mcp_server.py dataConfig=mock

服务器将于启动 http://localhost:8086

检查集装箱状态

# Check if container is running
docker ps

# View container logs
docker logs mcp-server

# Check health status
docker inspect --format='{{.State.Health.Status}}' mcp-server

服务器端点

端点	方法	描述
`/mcp`	职位	主MCP端点（JSON-RPC 2.0）
`/`	GET	服务器信息
`/health`	GET	健康检查
`/images`	GET	列出所有生成的图像及其元数据
`/{filename}`	GET	提供生成的图像（例如。， `generated_image_123.png`)

使用MCP协议

步骤1：初始化连接

POST /mcp
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {
            "name": "your-client",
            "version": "1.0.0"
        }
    }
}

步骤2：发送初始化通知

POST /mcp
{
    "jsonrpc": "2.0",
    "method": "initialized",
    "params": {}
}

步骤3：列出可用工具

POST /mcp
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
}

第四步：使用工具

示例：将图像转换为base64

POST /mcp
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "image_to_base64",
        "arguments": {
            "url": "https://example.com/image.jpg"
        }
    }
}

示例：使用AI生成场景

POST /mcp
{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
        "name": "img_scene_generator",
        "arguments": {
            "prompt": "Transform this into a futuristic cyberpunk scene",
            "encodedFilePath": "/path/to/encoded/image/file.txt"
        }
    }
}

配置

环境变量

OPENAI_API_KEY：必需 img_scene_generator 工具
ENCODED_IMG_DIR：用于存储编码图像的目录（可选）
GENERATED_IMG_DIR：用于存储生成图像的目录（可选）

默认目录（未设置环境变量时）：

编码图像： /Users/jasbirsingh/Downloads/img_server/encoded_img
生成的图像： /Users/jasbirsingh/Downloads/img_server/generated_img

命令行选项

dataConfig=mock：以模拟模式运行（没有真正的API调用）
dataConfig=real：以实模式运行（默认）

开发与测试

测试服务器

健康检查：
```
curl http://localhost:8086/health
```

列出工具：

curl -X POST http://localhost:8086/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

模拟模式测试： 与一起跑步 dataConfig=mock 在没有OpenAI API调用的情况下进行测试

文件结构

demo-mcp-server/
├── mcp_server.py          # Main server implementation
├── requirements.txt       # Python dependencies
├── Dockerfile            # Docker container configuration
├── README.md             # This file
├── myenv/                # Virtual environment (local development)
└── data/                 # Generated files (when using Docker volumes)
    ├── encoded_img/      # Base64 encoded image files
    └── generated_img/    # AI generated image files

生成的文件

编码图像: encode-img-{timestamp}.txt
生成的图像: generated_image_{timestamp}.png

故障排除

常见问题

ModuleNotFoundation错误：没有名为“aiohttp”的模块
```
pip install aiohttp
```
OpenAI API错误
- 验证API密钥设置是否正确
- 检查您的OpenAI帐户是否有足够的积分
- 使用模拟模式进行测试： python mcp_server.py dataConfig=mock
目录权限错误
- 确保应用程序对配置的目录具有写权限
- 如果目录不存在，服务器将自动创建目录

日志

服务器提供详细的日志记录。检查控制台输出：

请求处理状态
工具执行进度
错误详细信息和堆栈跟踪

需求

看 requirements.txt 有关依赖关系的完整列表：

fastapi -Web框架
uvicorn[standard] -ASGI服务器
openai -OpenAI API客户端
aiohttp -异步HTTP客户端
requests -HTTP库
pydantic -数据验证
python-dotenv -环境变量管理

贡献

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求

许可证

此项目遵循MIT许可条款。

需要帮助？ 检查服务器日志以获取详细的错误消息和调试信息。