McpServer

McpServer

用于集成 AI 模型和管理图书的 Model Context Protocol（MCP）实现服务。

概述

McpServer 是一个完整的解决方案，可将 Ollama 的 AI 模型与图书管理 API 集成。该项目实现了 MCP（Model Context Protocol），并提供 HTTP 接口，以便通过 API 执行工具。

系统由三个主要组件组成：

• McpServer：基于 .NET 的 MCP 协议实现
• Livros API：用于管理图书数据的 API
• Ollama：用于运行 AI 模型的服务

系统要求

• Docker 和 Docker Compose
• .NET 9.0（用于开发）
• 至少 8GB RAM（运行较大的 AI 模型建议使用 16GB）
• 10GB 磁盘空间

安装和运行

方法 1：使用 Docker Compose（推荐）

1. 克隆代码库：

   git clone https://github.com/Adriano-Severino/McpServer.git
   cd McpServer
   

2. 使用 Docker Compose 运行系统：

   docker-compose up -d
   

3. 检查所有服务是否正在运行：

   docker-compose ps
   

方法 2：在本地运行（用于开发）

1. 克隆代码库：

   git clone https://github.com/Adriano-Severino/McpServer.git
   cd McpServer
   

2. 在本地或通过 Docker 运行 Ollama：

   docker run -d -p 11434:11434 -v ollama_data:/root/.ollama --name ollama ollama/ollama
   

3. 运行 Livros API：

   cd Livros
   dotnet run
   

4. 配置 McpServer 的环境变量：

   set OLLAMA_BASE_URL=http://localhost:11434
   set API_BASE_ADDRESS=http://localhost:5000/api/
   

5. 运行 McpServer：

   cd McpServer
   dotnet run
   

系统使用方法

系统运行后，你可以访问：

API 端点

• MCP 服务：http://localhost:5500

  • 工具列表：http://localhost:5500/api/tools
  • OpenAPI 文档：http://localhost:5500/api/openapi.json
  • 工具执行端点：http://localhost:5500/api/execute（POST）

• Livros API：http://localhost:5000

  • 用于管理图书的 REST API

与 Open WebUI 集成

与 Open WebUI 集成：

1. 启动 Open WebUI（如果未使用完整的 docker-compose）：

   docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=http://localhost:11434 -e MCP_SERVER_URL=http://localhost:5500 ghcr.io/open-webui/open-webui:cuda
   

2. 访问 Open WebUI：http://localhost:3000

3. 配置与 MCP Server 的连接：

   • URL：http://localhost:5500/api/openapi.json

可用工具

MCP Server 提供以下工具：

图书管理

• ObterAsync：搜索图书，可按标题筛选
• ObterPorAutor：搜索图书，可按作者筛选
• CadastrarAsync：创建/登记新图书
• AtualizarAsync：更新现有图书的数据

与 Ollama 集成

• ListModels：列出 Ollama 中可用的模型
• GenerateResponse：使用 Ollama 模型生成回复

系统实用工具

• VerificarConectividade：检查组件之间的连通性
• ExibirConfiguracao：显示 MCP Server 的连接配置

使用示例

示例 1：列出图书

// POST para http://localhost:5500/api/execute
{
  "tool": "ObterAsync",
  "parameters": {
    "titulo": "O Senhor dos Anéis"
  }
}

示例 2：登记图书

// POST para http://localhost:5500/api/execute
{
  "tool": "CadastrarAsync",
  "parameters": {
    "livro": {
      "titulo": "O Hobbit",
      "autor": "J.R.R. Tolkien",
      "anoPublicacao": 1937,
      "genero": "Fantasia"
    }
  }
}

示例 3：使用 Ollama 生成回复

// POST para http://localhost:5500/api/execute
{
  "tool": "GenerateResponse",
  "parameters": {
    "model": "llama3",
    "prompt": "Escreva um resumo sobre O Senhor dos Anéis"
  }
}

配置

环境变量

• OLLAMA_BASE_URL：Ollama 服务的基础 URL（默认值：http://ollama:11434）
• API_BASE_ADDRESS：Livros API 的基础地址（默认值：http://livros-api:5000/api/）

故障排除

连通性问题

如果服务之间出现连通性问题：

1. 检查所有容器是否正在运行：

   docker-compose ps
   

2. 使用连通性检查工具：

   // POST para http://localhost:5500/api/execute
   {
     "tool": "VerificarConectividade",
     "parameters": {}
   }
   

3. 检查容器日志：

   docker-compose logs mcpserver
   docker-compose logs livros-api
   docker-compose logs ollama
   

Ollama 模型问题

如果模型未能加载：

1. 检查 Ollama 是否正在运行
2. 检查 Ollama 中是否有该模型：

   docker exec -it ollama ollama list
   

3. 如有需要，下载模型：

   docker exec -it ollama ollama pull llama3
   

系统架构

┌─────────────┐     ┌──────────────┐     ┌───────────┐
│  Open WebUI │────►│  MCP Server  │────►│  Ollama   │
└─────────────┘     └──────────────┘     └───────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Livros API  │
                    └──────────────┘

开发

为项目做出贡献：

1. Fork 代码库
2. 为你的功能创建分支（git checkout -b feature/nome-da-feature）
3. 提交更改（git commit -am 'Adiciona funcionalidade X'）
4. 将更改推送到分支（git push origin feature/nome-da-feature）
5. 创建 Pull Request