AI导哈

书籍管理API服务

一个基于FastAPI构建的书籍管理服务，提供RESTful API和MCP工具集成，支持对SQLite数据库中的书籍进行CRUD操作。

  • by goagiq
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 goagiq/mcp-fastapi-server

使用说明

FastAPI图书收集MCP服务器

使用FastAPI构建的模型上下文协议（MCP）服务器，用于管理图书收藏。该应用程序提供了RESTful API和MCP工具集成，用于对存储在SQLite数据库中的书籍执行CRUD操作。

特性

  • 完成图书管理的CRUD操作
  • 带有自动OpenAPI文档的FastAPI
  • 使用SQLAlchemy ORM的SQLite数据库
  • 模型上下文协议（MCP）集成
  • 用于数据验证的Pydantic模型
  • 交互式API文档
  • 图书列表的分页支持
  • 自动数据库初始化

先决条件

  • Python 3.13或更高版本
  • 无外部依赖（使用SQLite）

安装

  1. 克隆或下载此项目

  2. 使用uv安装依赖项：

    uv sync

    或者使用pip：

    pip install fastapi[standard] sqlalchemy pydantic uvicorn fastapi-mcp

用法

运行服务器

使用MCP集成启动FastAPI服务器：

python main.py

这将启动服务器 http://127.0.0.1:8000 同时具有REST API和MCP功能。

或者，您可以直接使用uvicorn跑步：

uvicorn main:app --host 127.0.0.1 --port 8000

访问API

  • 交互式文档: http://127.0.0.1:8000/docs （Swagger用户界面）
  • 替代文件: http://127.0.0.1:8000/redoc （ReDoc）
  • 根端点: http://127.0.0.1:8000/ （欢迎页面有链接）

API终点

根

  • 得到/：带有导航链接的欢迎信息
    • 返回：欢迎信息以及文档和图书列表的链接

图书管理

  • GET/书籍：检索所有分页书籍

    • 查询参数：
      • skip （int，默认值=0）：要跳过的书籍数量
      • limit （int，默认值=10）：要返回的最大图书数
    • 返回：书籍列表

  • GET/books/{book_id}：检索特定书籍

    • 路径参数：
      • book_id （int）：书籍的唯一标识符
    • 返回：书籍详细信息或404（如果未找到）

  • POST/书籍：创建新书

    • 请求正文：
      {
  "title": "Book Title",
  "read": false
}
    • 返回：已创建具有指定ID的书籍

  • PUT/书籍/{book_id}：更新现有书籍

    • 路径参数：
      • book_id （int）：书籍的唯一标识符
    • 请求正文：
      {
  "title": "Updated Book Title",
  "read": true
}
    • 返回：已更新图书详细信息，如果未找到，则返回404

  • 删除/书籍/{book_id}：删除一本书

    • 路径参数：
      • book_id （int）：书籍的唯一标识符
    • 返回：已删除图书详细信息，如果未找到，则返回404

数据模型

图书模型（数据库）

class Book(Base):
    id: int (Primary Key)
    title: str (Indexed)
    read: bool (Default: False)

请求/响应模型

BookCreate（请求）

{
  "title": "string",
  "read": false  # Optional, defaults to false
}

BookResponse（响应）

{
  "id": 1,
  "title": "string",
  "read": false
}

MCP集成

此服务器包括使用FastAPI MCP的模型上下文协议（MCP）集成，它将以下操作作为MCP工具公开：

  • get_books -检索所有书籍
  • get_book -按ID检索特定书籍
  • create_book -创建新书
  • update_book -更新现有书籍
  • delete_book -删除一本书

这些工具可供MCP兼容客户端和AI助手用于图书管理操作。

MCP工具使用示例

# The MCP tools are automatically exposed and can be called by MCP clients
# Example operations available:
# - get_books(skip=0, limit=10)
# - get_book(book_id=1)
# - create_book(title="New Book", read=False)
# - update_book(book_id=1, title="Updated Title", read=True)
# - delete_book(book_id=1)

数据库

该应用程序使用SQLite进行数据存储，具有以下特点：

  • 数据库文件: test.db （自动创建）
  • 对象关系映射：带声明性基的SQLAlchemy
  • 连接：带自动会话管理的SQLite
  • 初始化：启动时会自动创建表

数据库模式

CREATE TABLE books (
    id INTEGER PRIMARY KEY,
    title VARCHAR,
    read BOOLEAN
);

示例用法

使用cURL

创建一本书：

curl -X POST "http://127.0.0.1:8000/books" \
     -H "Content-Type: application/json" \
     -d '{"title": "The Great Gatsby", "read": false}'

获取所有书籍：

curl -X GET "http://127.0.0.1:8000/books"

更新一本书：

curl -X PUT "http://127.0.0.1:8000/books/1" \
     -H "Content-Type: application/json" \
     -d '{"title": "The Great Gatsby", "read": true}'

使用Python请求

import requests

# Create a book
response = requests.post(
    "http://127.0.0.1:8000/books",
    json={"title": "1984", "read": False}
)
book = response.json()
print(f"Created book: {book}")

# Get all books
response = requests.get("http://127.0.0.1:8000/books")
books = response.json()
print(f"All books: {books}")

# Mark book as read
book_id = book["id"]
response = requests.put(
    f"http://127.0.0.1:8000/books/{book_id}",
    json={"title": "1984", "read": True}
)
updated_book = response.json()
print(f"Updated book: {updated_book}")

发展

项目结构

mcp-fastapi-server/
├── main.py              # Main FastAPI application
├── pyproject.toml       # Project configuration
├── README.md           # This file
├── test.db             # SQLite database (created at runtime)
├── uv.lock             # Dependency lock file
└── .gitignore          # Git ignore rules

依赖项

  • 快速 API：用于API的现代快速web框架
  • SQL炼金术：SQL工具包和ORM
  • 派丹蒂克：使用Python类型提示进行数据验证
  • 乌维科恩：闪电般快速的ASGI服务器
  • FastAPI-MCP：FastAPI的模型上下文协议集成

以开发模式运行

对于自动重新加载的开发：

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

错误处理

API包括正确的错误处理：

  • 404未找到：当具有指定ID的书籍不存在时
  • 422不可处理实体：当请求数据验证失败时
  • 500内部服务器错误：用于意外的服务器错误

错误响应遵循FastAPI标准格式：

{
  "detail": "Book not found"
}

测试

您可以使用以下方法测试API：

  1. 交互式文档：参观 /docs 用于Swagger UI测试
  2. 卷曲：使用命令行HTTP请求
  3. Python请求：程序化API测试
  4. 邮递员：从导入OpenAPI规范 /openapi.json

配置

应用程序使用以下默认配置：

  • 主机：127.0.0.1（本地主机）
  • 端口: 8000
  • 数据库：SQLite(test.db)
  • 载入：生产中禁用

要修改配置，请编辑 uvicorn.run() 打电话 main.py.

故障排除

常见问题

  1. 端口已在使用中

    • 更改端口 main.py 或使用端口8000终止进程

  2. 数据库权限错误

    • 确保应用程序目录中的写入权限

  3. 导入错误

    • 验证是否安装了所有依赖项： uv sync

  4. MCP工具不工作

    • 确保FastAPI MCP已正确安装和配置

日志记录

该应用程序使用FastAPI的内置日志记录。有关更详细的日志，请使用以下命令运行：

uvicorn main:app --log-level debug

贡献

请随时提交问题和增强请求！

许可证

本项目按原样提供，用于教育和发展目的。

相关 MCP