UNSA MCP Server
圣阿古斯丁国立大学（UNSA）计算机科学周的MCP（模型上下文协议）服务器。此项目提供了管理活动、演讲者、会议和语义嵌入的工具和服务。
📋 描述
UNSA MCP服务器是一个Spring Boot应用程序，它实现了MCP协议，提供了人工智能工具，能够：
- 活动管理管理年度学术活动
- 演讲者管理管理演讲者信息及其联系方式
- 会话管理组织讲座、研讨会和演示
- 语义搜索使用OpenAI嵌入进行智能搜索
- MCP集成支持MCP协议的服务器，用于与AI客户端集成
🏗️ 建筑学
后端
- 框架Spring Boot 3.5.6 配合 Java 21
- 数据库PostgreSQL 配备 pgvector 扩展用于嵌入向量
- 迁徙Flyway用于模式管理
- 人工智能（IA）Spring AI结合OpenAI进行嵌入生成
- 协议MCP服务器，用于与AI客户端集成
前端
- 框架使用 Material-UI 7.2.0 的 React
- 国家集中式国家管理
- UI（用户界面）与MUI（Material-UI）兼容的组件
🚀 安装与部署
先决条件
- Java 21及以上版本
- Maven 3.6及以上版本
- PostgreSQL 16+ 配备 pgvector 扩展
- Docker 和 Docker Compose（可选）
- OpenAI的API密钥
环境变量
Crea un archivo .env 在项目根目录下，包含以下变量：
# Base de datos
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=mcp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
# OpenAI
OPENAI_API_KEY=tu_clave_api_aqui选项1：使用Docker Compose进行部署（推荐）
- 克隆仓库：
git clone
cd unsa-mcp-external- 设置环境变量:
cp .env.example .env
# Edita .env con tus valores- 启动服务：
cd backend
docker-compose up -d- 执行迁移:
./mvnw flyway:migrate- 启动应用程序：
./mvnw spring-boot:run选项2：手动部署
- 配置 PostgreSQL：
-- Instala la extensión pgvector
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS unaccent;- 设置环境变量：
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=mcp
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
export OPENAI_API_KEY=tu_clave_api_aqui- 构建并执行:
cd backend
./mvnw clean package
java -jar target/unsa-mcp-0.0.1-SNAPSHOT.jar选项3：在生产环境中部署
- 配置生产数据库：
# Actualiza application.properties con los valores de producción
spring.datasource.url=jdbc:postgresql://prod-host:5432/mcp_prod
spring.datasource.username=prod_user
spring.datasource.password=prod_password- 构建JAR文件:
./mvnw clean package -Pproduction- 展开：
java -jar target/unsa-mcp-0.0.1-SNAPSHOT.jar🔧 设置
数据库
该项目使用以下主要表格：
- 事件年度活动（例如：2024年计算机科学周）
- 扬声器演讲者和发言人
- 会议/会话会议、讲座和研讨会
- 实体嵌入语义嵌入用于智能搜索
OpenAI的配置
# application.properties
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.embedding.options.model=text-embedding-3-smallMCP配置
# MCP Server Configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.protocol=STREAMABLE📚 API 端点
活动
GET /api/events- 列出事件POST /api/events- 创建事件GET /api/events/{id}- 获取特定事件
发言人/讲者
GET /api/speakers- 列出演讲者POST /api/speakers- Crear ponenteGET /api/speakers/{id}- 获取特定演讲者
会议/课程
GET /api/sessions- 列出会话POST /api/sessions- 创建会话GET /api/sessions/{id}- 获取特定会话
MCP 工具
GET /mcp/tools- 列出可用的MCP工具POST /mcp/tools/{toolName}- 运行MCP工具
🧪 测试
# Ejecutar tests
./mvnw test
# Ejecutar tests con cobertura
./mvnw test jacoco:report📊 监控和日志
日志
# Configuración de logging
logging.level.org.springframework.ai.mcp=DEBUG
logging.level.org.springframework.ai=DEBUG
logging.level.org.springframework.web=DEBUG健康检查
GET /actuator/health- 应用程序状态GET /mcp/debug- MCP调试信息
🔍 语义搜索
该系统包含语义搜索功能：
- 寻找演讲者按语义相似性查找扬声器
- 会话搜索按内容查找会议
- 自动嵌入新实体的嵌入自动生成
🛠️ 开发
项目结构
backend/
├── src/main/java/pe/unsa/mcp/
│ ├── controller/ # Controladores REST
│ ├── dto/ # Data Transfer Objects
│ ├── model/ # Entidades JPA
│ ├── repository/ # Repositorios de datos
│ ├── services/ # Lógica de negocio
│ └── mcp/ # Configuración MCP
├── src/main/resources/
│ ├── application.properties
│ └── db/migration/ # Migraciones Flyway
└── compose.yaml # Docker Compose代码标准
- 语言类名、方法名和变量名使用英文
- 评论仅用于非琐碎决策
- 验证集中化服务
- 错误处理使用Spring核心的异常处理
🚨 故障排除
常见问题
- 连接到 PostgreSQL 的错误：
- 验证 PostgreSQL 是否正在运行 - 在环境变量中确认凭据
- OpenAI API错误:
- 验证API密钥是否有效 - 确认你有可用的信用额度
- 迁移错误：
- 确认数据库具有所需的扩展 - 如有需要，请手动执行迁移
有用的日志
# Ver logs de la aplicación
tail -f logs/application.log
# Ver logs de Docker
docker-compose logs -f📝 许可证
这个项目是为圣阿古斯丁国立大学（UNSA）开发的。
🤝 贡献
- 分叉该项目
- 为你的功能创建一个分支（
git checkout -b feature/AmazingFeature) - 提交你的更改（
git commit -m 'Add some AmazingFeature') - 推送分支（
git push origin feature/AmazingFeature) - 打开一个拉取请求（Pull Request）