使用说明
HULFT MCP 服务器
用于使用AWS AI服务进行文档处理的模型上下文协议（MCP）服务器。提供文本提取、文档分类、字段提取等工具。
🚀 快速开始
生产
# Access production endpoint
curl https://mcp.hulftincpredev.net/health
发展
# Access development endpoint
curl https://mcp-dev.hulftincpredev.net/health
本地开发
# Build and run
./gradlew build
java -jar build/libs/hulft-mcp-1.0.0.jar
# Server starts on http://localhost:3333
🏗️ 建筑
环境
| 环境 | 分支 | URL | 资源 |
|---|---|---|---|
| 生产 | main |
https://mcp.hulftincpredev.net/mcp | 2个任务，512个CPU，1GB RAM |
| 发展 | develop |
https://mcp-dev.hulftincpredev.net/mcp | 1个任务，256个CPU，512MB RAM |
基础设施
- 平台：AWS云服务器Fargate
- 负载均衡器：使用HTTPS的应用程序负载平衡器
- 容器：Docker（linux/amd64）
- 日志记录：JSON格式的CloudWatch日志
- 域名系统：带有ACM SSL证书的Route53
📋 可用工具
文档处理
- 提取文本 -从PDF、Word、Excel、图像中提取文本
- classify文档 -使用AWS Comprehend/基岩对文档类型进行分类
- 提取字段 -使用AWS基岩提取结构化字段
- convert_to_markdown -将文档转换为Markdown格式
归档操作
- 提取存档 -提取ZIP/TAR档案
- list_存档 -列出存档内容
工作管理
- get_job_status -检查异步作业状态
- list_jobs -列出所有作业
- cancel_job -取消正在运行的作业
模式管理
- get_schema -获取字段提取模式
- list_schemas -列出可用架构
🔌 端点
MCP协议
POST /mcp-MCP JSON-RPC请求GET /mcp-SSE流（返回405-不支持）
健康检查
GET /health-服务健康状态
{
"status": "healthy",
"version": "2.1.0",
"service": "hulft-mcp",
"timestamp": 1737398400000
}
🔐 MCP协议合规性
实施MCP流式HTTP规范（2025-11-25）：
- ✅ 协议版本验证(
MCP-Protocol-Version头球 - ✅ 会话管理(
MCP-Session-Id头球 - ✅ 接受标头协商
- ✅ 源标头验证（DNS重新绑定保护）
- ✅ JSON-RPC 2.0错误响应
- ⚠️ SSE流（可选，返回405）
看 MCP_合作.md 了解详情。
🛠️ 发展
先决条件
- Java 17+
- 码头工人
- AWS CLI（用于部署）
- 预提交（用于git钩子）
设置
# Clone repository
git clone https://github.com/HULFT-Inc/hulft-mcp.git
cd hulft-mcp
# Install pre-commit hooks
pip install pre-commit
pre-commit install
# Build
./gradlew build
# Run tests
./gradlew test
# Check code quality
./gradlew pmdMain checkstyleMain
工作流程
- 创建要素分支：
git checkout -b feature/my-feature - 进行更改并提交（预提交钩子自动运行）
- 推送分支：
git push origin feature/my-feature - 创建Pull请求
main - 通过PR合并（触发部署）
备注：直接承诺 main 被预提交钩子阻塞。
🚢 部署
自动化（GitHub操作）
部署会自动触发：
- 推至
main→ 生产部署 - 推至
develop→ 开发部署
工作流使用OIDC进行AWS身份验证（无静态凭据）。
手动部署
# Build Docker image
docker buildx build --platform linux/amd64 -t hulft-mcp:latest .
# Push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 486560520867.dkr.ecr.us-east-1.amazonaws.com
docker tag hulft-mcp:latest 486560520867.dkr.ecr.us-east-1.amazonaws.com/hulft-mcp:latest
docker push 486560520867.dkr.ecr.us-east-1.amazonaws.com/hulft-mcp:latest
# Update ECS service
aws ecs update-service --cluster hulft-mcp-cluster --service hulft-mcp --force-new-deployment --region us-east-1
基础设施（地形）
cd terraform
# Production
terraform workspace select prod
terraform apply -var-file=prod.tfvars
# Development
terraform workspace select default
terraform apply -var-file=dev.tfvars
📊 监控
CloudWatch日志
# Production logs
aws logs tail /ecs/hulft-mcp --follow --region us-east-1
# Development logs
aws logs tail /ecs/hulft-mcp-dev --follow --region us-east-1
健康检查
# Check service health
curl https://mcp.hulftincpredev.net/health
# Check ECS service
aws ecs describe-services --cluster hulft-mcp-cluster --services hulft-mcp --region us-east-1
🏆 质量指标
- ✅ PMD： 0次违规（低于383次）
- ✅ 检查方式： 0次违规（低于46次）
- ✅ 测验： 54/54通过（100%）
- ✅ 新闻报道： 73.9%（超过70%阈值）
📚 文档
🔒 安全
- 带有ACM通配符证书的HTTPS
- 仅限TLS 1.3/1.2
- 源标头验证
- 会话管理
- 无静态AWS凭据（OIDC）
- 预提交钩子阻止私钥提交
💰 成本估算
- ECS Fargate：约30美元/月
- 应用程序负载平衡器：约20美元/月
- 数据传输：约5-10美元/月
- CloudWatch日志：约2美元/月
- ECR：约1美元/月
总计：约58-63美元/月
📝 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🤝 贡献
- 分叉存储库
- 创建特征分支
- 通过测试进行更改
- 确保所有质量检查通过
- 提交拉取请求
📞 支持
对于问题或疑问，请打开GitHub问题。
