图书馆MCP
演示工程 --仅用于当地发展和学习目的。请勿将其暴露于公共互联网或用于存储真实数据。
LibraryMCP是一个基于FastAPI的后端服务器，旨在作为库管理的模型上下文协议（MCP）工具调用源。它提供了一组API端点来管理图书馆系统中的图书、会员和贷款。
特性
- 图书管理：完整的CRUD，按标题、作者、类型和可用性进行过滤。
- 会员管理：注册、列出（带过滤器）、查看贷款历史和罚款的详细信息、更新和删除业务规则。
- 贷款管理：借款/归还工作流、活动贷款列表和精细计算。
- JWT身份验证：所有API端点（除
/auth/token)需要不记名代币。凭据可以通过环境变量进行配置。 - SQLite数据库：使用SQLAlchemy ORM的轻量级存储。
- 快速API：用于使用Python构建API的高性能web框架。
- CORS已启用：打开CORS，便于本地开发和浏览器演示。
- 简单前端演示：添加/列出书籍和成员的最小HTML页面。
- 播种工具：内置脚本，用于用初始示例数据填充数据库。
项目结构
libraryMCP/
├── backend/ # Application source code
│ ├── routers/ # API route handlers
│ │ ├── auth.py # Authentication endpoint (token issuance)
│ │ ├── books.py # Book-related endpoints
│ │ ├── loans.py # Loan-related endpoints
│ │ └── members.py # Member-related endpoints
│ ├── auth.py # JWT creation, verification, and get_current_user dependency
│ ├── crud.py # CRUD operations
│ ├── database.py # Database configuration and session management
│ ├── main.py # FastAPI application entry point (CORS + routers)
│ ├── models.py # SQLAlchemy database models
│ ├── schemas.py # Pydantic models for request/response validation
│ └── seed.py # Database seeding script
├── frontend/
│ └── index.html # Simple browser demo (books/members)
├── library.db # SQLite database file
├── openapi.json # Generated OpenAPI schema snapshot
├── pyproject.toml # Project dependencies and configuration
├── uv.lock # Lock file for dependencies
└── README.md # Project documentation先决条件
安装
- 克隆存储库：
git clone
cd libraryMCP- 安装依赖项：
uv sync- 在中配置凭据
.env（复制自.env并填写您的值）：
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="your-password"
SECRET_KEY="your-secret-key"
BACKEND_URL=http://localhost:8000用法
运行服务器
使用启动FastAPI服务器 uvicorn:
uv run uvicorn backend.main:app --reloadAPI将于 http://127.0.0.1:8000.
认证
除以下端点外的所有端点 POST /auth/token 需要JWT Bearer令牌。
获取令牌：
curl -X POST http://127.0.0.1:8000/auth/token \
-d "username=admin&password=your-password"答复：
{ "access_token": "", "token_type": "bearer" }使用令牌：
curl http://127.0.0.1:8000/books/ \
-H "Authorization: Bearer "令牌在30分钟后过期。通过配置凭据 ADMIN_USERNAME, ADMIN_PASSWORD，以及 SECRET_KEY 环境变量（或 .env).
API文档
服务器运行后，您可以访问交互式API文档：
- Swagger用户界面: http://127.0.0.1:8000/docs --点击 授权，呼叫
POST /auth/token首先获取令牌，然后将其粘贴到Bearer字段中 - ReDoc: http://127.0.0.1:8000/redoc
- OpenAPI JSON: http://127.0.0.1:8000/openapi.json （快照也位于
openapi.json)
为数据库播种
要用示例数据填充数据库，请运行种子脚本：
uv run python backend/seed.py简单前端演示（可选）
您可以使用一个很小的前端与API进行交互：
- 打开
frontend/index.html在浏览器中 - 确保后端运行在
http://localhost:8000（CORS已启用） - 使用UI添加/列出书籍和成员
MCP 服务器
MCP服务器将库的功能作为AI助手（Claude等）可以直接调用的工具公开。
运行MCP服务器
MCP服务器通过stdio进行通信。首先启动FastAPI后端，然后运行：
uv run python mcp_server/main_stdio.py服务器读取 BACKEND_URL, ADMIN_USERNAME，以及 ADMIN_PASSWORD 环境（或 .env).它在首次使用时自动获得JWT令牌，并在到期时刷新它。
连接到克劳德桌面
将以下内容添加到您的Claude Desktop配置中(claude_desktop_config.json):
{
"mcpServers": {
"library": {
"command": "uv",
"args": ["run", "python", "mcp_server/main_stdio.py"],
"env": {
"PYTHONPATH": "/absolute/path/to/libraryMCP"
}
}
}
}可用的MCP工具
| 工具 | 说明 |
|---|---|
search_books | 按标题、作者或流派搜索书籍 |
get_book | 按ID获取书籍的完整详细信息 |
add_book | 将新书添加到目录中 |
update_book | 更新图书元数据或副本计数 |
delete_book | 删除一本书（如果存在活动贷款，则被阻止） |
list_members | 列出具有可选筛选器的成员 |
register_member | 注册新库成员 |
get_member | 获取会员资料、贷款历史和罚款 |
delete_member | 删除成员（如果贷款有效或未支付罚款，则被阻止） |
borrow_book | 为会员借阅一本书 |
return_book | 归还借来的书，计算任何逾期罚款 |
get_loans | 列出会员的所有活动贷款 |
check_fines | 获取会员的未缴罚款总额 |
API端点概述
认证
POST /auth/token--获取JWT承载令牌（表单字段：username,password).
书籍
GET /books/--列出带有可选过滤器的书籍。
- 查询： title, author, genre, available_only
GET /books/{id}--按ID获取一本书。POST /books/--创建一本书（初始available_copies = total_copies).PUT /books/{id}--更新一本书。DELETE /books/{id}--删除一本书（如果有活动贷款，则被阻止）。
成员
GET /members/--使用筛选器和分页列出成员。
- 查询： skip, limit, name, email, is_active
GET /members/{id}--获取会员详细信息，包括贷款历史、有效贷款计数和罚款总额。POST /members/--注册新会员（需要唯一的电子邮件）。PUT /members/{id}--更新成员（不能在贷款有效时停用；电子邮件必须唯一/有效）。DELETE /members/{id}--删除成员（如果贷款有效或未支付罚款，则被阻止）。
贷款
POST /loans/borrow--借阅图书（会员必须处于活动状态；图书必须有可用副本；没有重复的活动借阅）。POST /loans/return--归还一本书（增加可用性；逾期计算罚款：0.50美元/天）。GET /loans/{member_id}--列出会员的活动贷款。GET /loans/{member_id}/fines--计算并返回会员的明细。