Appointment Scheduler MCP Server

预约计划程序MCP服务器

一种模型上下文协议（MCP）服务器，连接到PostgreSQL数据库以管理预约调度。使用FastMCP、SQLAlchemy和Alembic构建，用于数据库迁移。

🚀 特性

• 数据库集成：带有SQLAlchemy ORM的PostgreSQL数据库
• MCP协议：支持stdio和HTTP传输模式
• 数据库迁移：Alembic用于模式管理和迁移
• 预约管理：安排有验证的约会
• Docker支持：使用Docker Compose进行容器化部署
• 环境配置：使用.env文件进行安全的凭据管理

📋 先决条件

• Python 3.13+
• PostgreSQL数据库
• uv包管理器（推荐）或pip

🛠️ 安装

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/Juan-Andres-Motta/backend-mcp.git
cd backend-mcp

# Install dependencies
uv sync

使用pip

# Clone the repository
git clone https://github.com/Juan-Andres-Motta/backend-mcp.git
cd backend-mcp

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

# Install dependencies
pip install -r requirements.txt

⚙️ 配置

环境变量

创建一个 .env 项目根目录中的文件：

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password

# Database URL (constructed from above)
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

# MCP Server Configuration
MCP_TRANSPORT=stdio  # Options: stdio, http
MCP_HOST=0.0.0.0    # Only used for HTTP transport
MCP_PORT=8000       # Only used for HTTP transport

数据库设置

1. 使用Docker Compose （推荐）：

   docker-compose up -d postgres

1. PostgreSQL手动设置:

- 安装PostgreSQL - 创建一个数据库 - 更新 .env 使用您的数据库凭据

数据库迁移

运行数据库迁移以创建约会表：

# Using uv
uv run alembic upgrade head

# Using pip
alembic upgrade head

🚀 运行服务器

开发模式（stdio）

# Using uv
uv run python main.py

# Using pip
python main.py

HTTP模式

集 MCP_TRANSPORT=http 在你的 .env 文件：

# Using uv
uv run python main.py

# Using pip
python main.py

服务器将在以下时间可用 http://localhost:8000

Docker部署

# Build and run with Docker Compose
docker-compose up --build

# Run only the MCP server (requires external PostgreSQL)
docker build -t appointment-mcp .
docker run --env-file .env appointment-mcp

📖 API使用

MCP工具： schedule_appointment

在数据库中安排新的约会。

参数：

• name （string）：安排约会的人的全名
• identification_number （string）：身份证号码（身份证、护照等）
• phone （string）：电话号码
• date （字符串）：ISO格式的预约日期和时间（YYYY-MM-DDTHH:MM:SS）

例子：

{
  "name": "John Doe",
  "identification_number": "123456789",
  "phone": "+1234567890",
  "date": "2024-12-25T14:30:00"
}

答复：

{
  "result": "Success: Appointment scheduled for John Doe on 2024-12-25 14:30:00 (ID: 1)"
}

🏗️ 项目结构

backend-mcp/
├── main.py                 # Main MCP server application
├── pyproject.toml          # Project dependencies and configuration
├── uv.lock                 # uv lock file
├── alembic/                # Database migration files
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
├── .env                    # Environment variables (create this)
├── .env.example           # Environment variables template
├── Dockerfile             # Docker container configuration
├── docker-compose.yml     # Docker Compose configuration
├── .dockerignore          # Docker ignore file
├── .gitignore             # Git ignore file
└── README.md              # This file

🔧 发展

运行测试

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

数据库模式

这 appointments 表格结构：

CREATE TABLE appointments (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    identification_number VARCHAR(50) NOT NULL,
    phone VARCHAR(20) NOT NULL,
    date TIMESTAMP NOT NULL
);

添加新功能

1. 在中定义新的MCP工具 main.py
2. 如果需要，更新数据库模型
3. 为架构更改创建Alembic迁移
4. 更新此自述文件

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🆘 故障排除

常见问题

1. 数据库连接错误

- 检查你的 .env 文件配置 - 确保PostgreSQL正在运行 - 验证数据库凭据

1. 迁移错误

- 跑 alembic current 检查迁移状态 - 跑 alembic upgrade head 应用待处理的迁移

1. MCP传输问题

- 对于stdio模式：确保MCP客户端支持stdio传输 - 对于HTTP模式：检查端口是否未被使用

获取帮助

• 检查 FastMCP文档
• 审查 SQLAlchemy文档
• 检查 Alembic文件

📊 版本历史记录

• v1.0.0：具有基本预约安排功能的初始版本
• 与PostgreSQL的数据库集成
• Docker容器化
• MCP协议支持（stdio和HTTP）