FormFillMCP by xingyun-New - MCP Server

FormFillAPI MCP Server

一个基于MCP（Model Context Protocol）的表单填写和邮件发送服务器，支持Excel表单自动填写、邮件发送和数据库记录功能。

功能特性

核心功能

Excel表单填写: 支持现有模板填写和新建表单
邮件发送: 支持SMTP邮件服务器发送带附件的邮件
数据库记录: 自动记录所有表单创建信息到MongoDB
高级查询: 支持模糊查询、时间查询和多字段排序

传输方式

stdio: 标准输入输出传输
SSE: Server-Sent Events传输
streamable_http: HTTP流式传输

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

复制 env_example.txt 为 .env 并配置：

# MongoDB数据库配置
MONGO_URI=mongodb://localhost:27017/
MONGO_DATABASE=formfill_api
MONGO_COLLECTION=forms

# 邮件服务器配置
SMTP_HOST=your-smtp-server.com
SMTP_PORT=587
SMTP_USERNAME=your-email@example.com
SMTP_PASSWORD=your-password
SMTP_FROM_EMAIL=your-email@example.com
SMTP_USE_TLS=true
SMTP_USE_SSL=false

# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
PUBLIC_HOST=your-domain.com

3. 启动服务器

stdio模式

python -m src.formfill_api.mcp.server

HTTP模式

python -m src.formfill_api.mcp.http_server

可用工具

表单操作

formfill_health_check: 检查服务状态
formfill_list_templates: 列出可用模板
formfill_get_template: 获取模板信息
formfill_preview_template: 预览模板字段
formfill_fill_form: 填写表单

邮件功能

formfill_send_email: 发送邮件
formfill_email_health: 检查邮件服务状态

数据库查询

formfill_search_form_records: 高级搜索表单记录
formfill_get_form_records: 获取表单记录列表
formfill_get_form_record_by_id: 获取记录详情
formfill_get_database_stats: 获取数据库统计

数据库功能

自动记录

每次表单创建时，系统会自动记录以下信息：

表单名称和内容
模板路径和输出文件
填写数量和总字段数
文件大小和路径
处理时间和错误信息
用户信息（IP、User-Agent等）

高级查询

支持多种查询方式：

精确查询: 按表单名称精确匹配
模糊查询: 按表单内容关键词模糊搜索
时间查询: 支持日期范围查询
状态筛选: 按表单状态筛选
多字段排序: 支持按创建时间、更新时间、表单名称、填写数量、文件大小排序

查询示例

{
  "form_name": "员工信息表",
  "form_content_keywords": "姓名",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "status": "created",
  "sort_by": "created_at",
  "sort_order": "desc",
  "limit": 50,
  "skip": 0
}

使用示例

1. 填写表单

{
  "formName": "员工信息表",
  "formContent": {
    "row3": {"col2": "张三"},
    "row4": {"col2": "技术部"},
    "row5": {"col2": "工程师"}
  }
}

2. 发送邮件

{
  "mailTo": "recipient@example.com",
  "mailTitle": "员工信息表",
  "mailContent": "请查收附件",
  "download_url": "http://localhost:8080/api/download/员工信息表_已填写_20241201_143022.xlsx"
}

3. 搜索表单记录

{
  "form_content_keywords": "张三",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "sort_by": "created_at",
  "sort_order": "desc",
  "limit": 10
}

项目结构

FormFillAPI/
├── src/
│   └── formfill_api/
│       ├── config.py              # 配置文件
│       ├── services/
│       │   ├── form_service.py    # 表单服务
│       │   ├── email_service.py   # 邮件服务
│       │   └── database_service.py # 数据库服务
│       ├── mcp/
│       │   ├── server.py          # stdio服务器
│       │   └── http_server.py     # HTTP服务器
│       └── utils/
│           └── dependencies.py     # 依赖检查
├── templates/                     # Excel模板目录
├── output/                       # 输出文件目录
├── examples/                     # 示例代码
├── document_md/                  # 文档
├── requirements.txt              # 依赖列表
└── README.md                    # 项目说明

配置说明

MongoDB配置

MONGO_URI: MongoDB连接字符串
MONGO_DATABASE: 数据库名称
MONGO_COLLECTION: 集合名称

邮件配置

SMTP_HOST: SMTP服务器地址
SMTP_PORT: SMTP端口
SMTP_USERNAME: 邮箱用户名
SMTP_PASSWORD: 邮箱密码
SMTP_FROM_EMAIL: 发件人邮箱
SMTP_USE_TLS: 是否使用TLS
SMTP_USE_SSL: 是否使用SSL

服务器配置

SERVER_HOST: 服务器监听地址
SERVER_PORT: 服务器端口
PUBLIC_HOST: 公网访问地址

故障排除

1. MongoDB连接失败

检查MongoDB服务是否运行
验证连接字符串格式
检查网络连接

2. 邮件发送失败

检查SMTP服务器配置
验证邮箱用户名和密码
检查防火墙设置

3. 表单填写失败

检查openpyxl是否安装
验证模板文件格式
检查输出目录权限

开发说明

添加新工具

在 list_tools() 中添加工具定义
在 call_tool() 中添加处理逻辑
更新文档和示例

扩展数据库功能

在 DatabaseService 中添加新方法
在MCP服务器中添加对应工具
更新查询指南文档

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！