MCP全栈服务器
用Kotlin实现的MCP（模型上下文协议）全栈服务器，使AI代理能够自主构建和管理应用程序。
概述
该服务器实现了MCP协议，为AI代理提供了强大的功能：
- 文件系统操作：安全的文件读取、写入和目录管理
- Bash执行：通过白名单和验证安全执行命令
- GitHub集成：版本控制操作（git命令）
- 知识图谱记忆：用于AI上下文的持久存储系统
- 数据库连接器：PostgreSQL、MongoDB和MySQL集成
- 资源管理：自定义文档和资源处理
特性
✅ 安全第一
- 路径遍历保护
- 命令白名单
- 文件大小和扩展名验证
- 危险模式检测
✅ Kubernetes就绪
- Docker支持
- 包括Kubernetes清单
- 健康检查和准备情况调查
- 资源限制和请求
✅ 可观察对象
- 结构化日志记录
- 健康和准备终点
- 指标支持（计划中）
✅ CI/CD就绪
- 使用GitHub Actions自动构建Docker
- Docker Hub集成
- 多分支部署支持（主/开发）
- Kubernetes部署自动化
快速开始
先决条件
- JDK 21+
- Gradle 8.10+
- Kotlin 2.2.0+
建筑
./gradlew build跑步
./gradlew run或者使用自定义配置：
export MCP_HOST=0.0.0.0
export MCP_PORT=3000
export MCP_WORKING_DIR=/workspace
./gradlew run使用Docker运行
docker build -t mcp-fullstack-server -f docker/Dockerfile .
docker run -p 3000:3000 mcp-fullstack-server测试
运行测试
# Run all tests
./gradlew test
# Run specific test class
./gradlew test --tests "BashExecutorTest"
# Run with coverage report
./gradlew test jacocoTestReport测试覆盖率
- 总测试：57项测试（53项有效，4项暂时禁用）
- 通过率：100%的主动测试（53/53通过）；4项测试暂时禁用
- 按模块覆盖:
- 文件系统：100% - Bash：100% - GitHub：100% - 资源：100% - PostgreSQL：100% - MongoDB：100% - 内存：71%（由于JSONL序列化问题，2个测试被禁用）
有关详细的测试说明，请参阅 测试指南.md.
配置
服务器通过以下方式配置 src/main/resources/application.conf。您可以使用环境变量覆盖设置：
服务器配置
MCP_HOST：服务器主机（默认值：0.0.0.0）MCP_PORT：服务器端口（默认值：3000）
文件系统配置
MCP_ALLOWED_DIRS：逗号分隔的允许目录列表MCP_MAX_FILE_SIZE：最大文件大小（以字节为单位）（默认值：10MB）
Bash配置
MCP_ALLOWED_COMMANDS：逗号分隔的允许命令列表MCP_WORKING_DIR：bash命令的工作目录MCP_COMMAND_TIMEOUT：命令超时（秒）（默认值：300）
GitHub配置
MCP_REPO_PATH：git存储库的路径GITHUB_TOKEN：GitHub个人访问令牌
数据库配置
POSTGRES_HOST,POSTGRES_PORT,POSTGRES_DB,POSTGRES_USER,POSTGRES_PASSWORDMONGODB_CONNECTION_STRING,MONGODB_DB
内存配置
MCP_MEMORY_PATH：知识图存储路径
项目结构
mcp-fullstack-server/
├── src/main/kotlin/com/apptolast/mcp/
│ ├── Application.kt # Main application entry point
│ ├── server/
│ │ └── ServerConfig.kt # Configuration management
│ ├── modules/
│ │ ├── filesystem/ # Filesystem operations
│ │ ├── bash/ # Bash command execution
│ │ ├── github/ # Git/GitHub integration
│ │ ├── memory/ # Knowledge graph memory
│ │ ├── database/ # Database connectors
│ │ └── resources/ # Resource management
│ ├── transport/ # MCP transport layers
│ ├── security/ # Security validation
│ └── util/ # Utilities and protocol definitions
├── src/main/resources/
│ ├── application.conf # Application configuration
│ └── logback.xml # Logging configuration
├── docker/
│ └── Dockerfile # Docker image definition
└── k8s/ # Kubernetes manifestsAPI终点
健康和状态
GET /：服务器信息GET /health：健康检查GET /ready：准备状态检查GET /info：服务器功能和版本
模块
文件系统模块
通过以下方式提供安全的文件系统操作：
- 路径验证和遍历保护
- 文件大小限制
- 扩展白名单
- 读取、写入、列出、创建和删除操作
Bash执行器模块
通过以下方式安全执行命令：
- 命令白名单
- 危险模式检测
- 超时保护
- 工作目录隔离
内存模块
持久AI记忆的知识图：
- 实体创建和存储
- 关系管理
- 图搜索和遍历
- 基于JSONL的存储
安全
服务器实现了多个安全层：
- 路径验证：所有文件系统操作都会根据允许的目录验证路径
- 命令白名单：只能执行明确允许的命令
- 危险模式检测：阻止已知的危险命令模式
- 文件大小限制：防止大文件操作
- 扩展过滤：只能访问允许的文件扩展名
- 超时保护：命令有执行时间限制
发展
运行测试
./gradlew test代码风格
这个项目遵循Kotlin编码规范。格式化代码：
./gradlew ktlintFormat部署
码头工人
该项目包括带有GitHub Actions的自动化CI/CD：
# Automated deployment (triggered on push to main/develop)
git push origin main看 .github/QUICKSTART.md 获取完整的CI/CD文档。
手动Docker构建
docker build -t mcp-fullstack-server -f docker/Dockerfile .
docker run -p 3000:3000 mcp-fullstack-serverKubernetes
应用Kubernetes清单：
kubectl apply -f k8s/这将创建：
- 使用MCP服务器进行部署
- 内部/外部访问服务
- 用于配置的ConfigMap
- 敏感数据的秘密
- 持久卷数据存储索赔
有关CI/CD构建后的Kubernetes自动更新，请参阅 .github/workflows/README.md.
许可证
有关详细信息，请参阅LICENSE文件。
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加测试
- 提交拉取请求
支持
对于问题和疑问：
- 在GitHub上创建问题
- 检查技术规范文件
路线图
完整的实施路线图见技术规范文件，包括：
- 第一阶段：基础（文件系统、Bash）
- 第二阶段：Git和内存集成
- 第3阶段：数据库连接器
- 第四阶段：集装箱化和K8s
- 第5阶段：可观察性和测试
- 第6阶段：硬化和生产
技术规范
有关详细的技术信息、体系结构和实现细节，请参阅 McpServerTecnicalDocument.txt.