书籍API MCP服务器
一个模型上下文协议（MCP）服务器，为人工智能助手提供图书管理工具。该服务器在AI应用程序和应用程序之间提供了一座桥梁。NET图书API，通过标准化MCP工具调用实现无缝图书收藏管理。
这个。此MCP服务器与之交互的.NET Book API后端位于： .
特性
- MCP协议支持：实现用于工具发现和执行的模型上下文协议
- RESTful API集成：连接到a。NET图书API后端
- 全面的CRUD操作：书籍的完整创建、阅读、更新和删除功能
- FastAPI框架：现代、快速、易于维护的Python web框架
- 类型安全模型：使用Pydantic进行稳健的数据验证
- 错误处理：全面的错误处理，错误信息清晰
可用工具
MCP服务器公开了以下工具：
1. list_books
从数据库中检索所有书籍。
参数：
- 无
退货：
- 具有以下字段的书籍对象数组：
- id （整数）：唯一图书标识符 - title （string）：书名 - author （string）：书籍作者 - isbn （string）：国际标准书号 - publishedDate （string）：ISO 8601格式的发布日期 - createdAt （string）：记录创建时间戳
示例用法：
result = BookService.list_books()
# Returns: List of all books in the database______________________________________________________________________
2. get_book
按ID检索特定书籍。
参数：
book_id（整数，必填）：要检索的书籍的唯一标识符
退货：
- 包含完整详细信息的图书对象，如果找不到图书，则出错
示例用法：
result = BookService.get_book(1)
# Returns: Book with ID 1______________________________________________________________________
3. create_book
在数据库中创建一本新书。
参数：
book_data（object，必填）：图书信息对象包含：
- id （整数，可选）：书籍的唯一标识符 - title （string，必填）：书名 - author （string，必填）：本书作者 - isbn （字符串，可选）：书籍的ISBN - publishedDate （字符串，可选）：发布日期 ISO 8601 UTC格式 （必须以“Z”结尾。， 2024-04-11T00:00:00Z)
退货：
- 已创建包含所有字段的图书对象，包括已生成的
createdAt时间戳
示例用法：
book_data = {
"title": "The Great Gatsby",
"author": "F. Scott Fitzgerald",
"isbn": "978-0743273565",
"publishedDate": "1925-04-10T00:00:00Z"
}
result = BookService.create_book(book_data)重要提示： 这 publishedDate 字段必须采用ISO 8601 UTC格式，以“Z”结尾，以确保PostgreSQL兼容性。
______________________________________________________________________
4. update_book
更新现有书籍的信息。
参数：
book_id（整数，必填）：要更新的书籍的唯一标识符book_data（object，必填）：更新的图书信息对象包含：
- id （整数）：书籍的ID（必须匹配 book_id) - title （字符串，可选）：新标题 - author （字符串，可选）：新作者 - isbn （字符串，可选）：新ISBN - publishedDate （字符串，可选）：中的新发布日期 ISO 8601 UTC格式 （必须以“Z”结尾）
退货：
- 如果更新成功，则显示成功消息，如果找不到书籍，则显示错误
示例用法：
book_data = {
"id": 1,
"title": "Updated Title",
"author": "Updated Author",
"isbn": "978-1234567890",
"publishedDate": "2023-01-01T00:00:00Z"
}
result = BookService.update_book(1, book_data)______________________________________________________________________
5. delete_book
从数据库中删除一本书。
参数：
book_id（整数，必填）：要删除的书籍的唯一标识符
退货：
- 如果删除成功，则显示成功消息，如果找不到书籍，则显示错误
示例用法：
result = BookService.delete_book(1)
# Returns: Success message confirming deletion______________________________________________________________________
安装说明
先决条件
- Python 3.8或更高版本
- 访问正在运行的Books API实例（默认值：
http://localhost:5288) - 虚拟环境（推荐）
安装
- 克隆或导航到项目目录：
cd book-api-mcp-server- 创建并激活虚拟环境：
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项：
pip install fastapi uvicorn requests pydantic或者如果你有 requirements.txt 文件：
pip install -r requirements.txt- 配置图书API URL:
编辑 services.py 并更新 BOOKS_API_URL 如果您的Books API在不同的主机/端口上运行，则为常量：
BOOKS_API_URL = "http://localhost:5288" # Update as needed- 运行服务器：
python run.py服务器将于启动 http://0.0.0.0:8080 默认情况下。
您可以使用环境变量自定义主机和端口：
export MCP_SERVER_HOST=localhost
export MCP_SERVER_PORT=8080
python run.py测试服务器
- 检查服务器运行状况：
curl http://localhost:8080/health- 列出可用工具：
curl http://localhost:8080/tools- 运行测试套件：
python test_tools.py______________________________________________________________________
配置
环境变量
MCP_SERVER_HOST：服务器主机地址（默认值：0.0.0.0)MCP_SERVER_PORT：服务器端口号（默认值：8080)BOOKS_API_URL：书籍API的基本URL（在中配置services.py，默认值：http://localhost:5288)
光标集成
要将此MCP服务器与Cursor一起使用，请将以下内容添加到您的 ~/.cursor/mcp.json:
{
"mcpServers": {
"books-api": {
"command": "python3",
"args": ["/path/to/book-api-mcp-server/run.py"]
}
}
}注： 更新MCP配置后重新启动Cursor以使更改生效。
______________________________________________________________________
API终点
MCP服务器公开以下HTTP端点：
GET /：具有服务器信息的根端点GET /tools：列出所有可用的MCP工具POST /tool-calls：执行一个或多个工具调用GET /health：健康检查端点GET /docs：交互式API文档（FastAPI Swagger UI）
______________________________________________________________________
使用示例
使用Python客户端
from services import BookService
import json
# List all books
books = BookService.list_books()
print(json.dumps(books.result, indent=2))
# Get a specific book
book = BookService.get_book(1)
print(json.dumps(book.result, indent=2))
# Create a new book
new_book = {
"title": "1984",
"author": "George Orwell",
"isbn": "978-0451524935",
"publishedDate": "1949-06-08T00:00:00Z"
}
result = BookService.create_book(new_book)
print(json.dumps(result.result, indent=2))
# Update a book
updated_data = {
"id": 1,
"title": "Nineteen Eighty-Four",
"author": "George Orwell"
}
result = BookService.update_book(1, updated_data)
# Delete a book
result = BookService.delete_book(1)使用HTTP API
# List all tools
curl http://localhost:8080/tools
# Call a tool
curl -X POST http://localhost:8080/tool-calls \
-H "Content-Type: application/json" \
-d '{
"tool_calls": [
{
"name": "list_books",
"parameters": {}
}
]
}'______________________________________________________________________
项目结构
book-api-mcp-server/
├── main.py # FastAPI application and server setup
├── routes.py # API route handlers for MCP endpoints
├── tools.py # Tool definitions and schemas
├── services.py # Business logic and Books API integration
├── models.py # Pydantic models for data validation
├── config.py # Configuration settings
├── run.py # Server entry point
├── test_tools.py # Test suite for validating tools
├── requirements.txt # Python dependencies
└── README.md # This file______________________________________________________________________
日期格式要求
重要提示： 所有日期字段(publishedDate)必须以ISO 8601 UTC格式提供，以“Z”结尾。这是PostgreSQL兼容性所必需的。
正确格式：
2024-04-11T00:00:00Z2023-05-11T12:30:45Z
格式不正确（将导致错误）：
2024-04-11T00:00:00（缺少“Z”）2024-04-11（未完全符合ISO 8601标准）04/11/2024（非ISO 8601）
______________________________________________________________________
技术
- Python 3.8+：编程语言
- 快速API：用于构建API的现代web框架
- Uvicorn：用于运行FastAPI的ASGI服务器
- 派丹蒂克：使用Python类型注释进行数据验证
- 请求：：用于对图书API进行API调用的HTTP库
______________________________________________________________________
错误处理
所有工具返回a ToolCallResult 具有以下结构的对象：
{
"result": | None, # Result data if successful
"error": | None # Error message if operation failed
}常见错误场景：
- 404未找到：指定ID的图书不存在
- 400错误请求：输入数据无效（例如，缺少必填字段、日期格式无效）
- 500服务器错误：数据库或API连接问题
- 连接错误：无法访问书籍API
______________________________________________________________________
故障排除
服务器无法启动
- 检查端口8080是否已在使用中
- 验证Python版本（3.8+）
- 确保安装了所有依赖项
工具返回连接错误
- 验证书籍API是否正在运行并可访问
- 检查
BOOKS_API_URL在services.py - 直接测试书籍API：
curl http://localhost:5288/books
日期格式错误
- 确保UTC时区的所有日期都以“Z”结尾
- 使用完整的ISO 8601格式：
YYYY-MM-DDTHH:MM:SSZ
______________________________________________________________________
许可证
该项目是图书管理系统演示的一部分。