wsg courses MCP

WSG课程API MCP服务器

MCP（模型上下文协议）服务器，为AI代理提供访问新加坡技能未来WSG课程API的权限

🌟 特性

• 10课程API终点：完全访问新加坡的课程目录
• 证书身份验证：使用WSG API进行安全的mTLS身份验证
• MCP协议支持：通过模型上下文协议与AI代理进行本地集成
• FastAPI后端：具有自动文档的高性能异步API
• 类型安全：对请求和响应进行完整的Pydantic验证
• 云就绪：Docker和Google Cloud Run部署支持
• 生产等级：全面的测试、监控和错误处理
• 自动缩放：使用Cloud Run时，请求数为零到数百万

📋 目录

• 快速开始
• 先决条件
• 安装
• 配置
• 用法
• API终点
• MCP工具
• 发展
• 测试
• 部署
• 安全
• 贡献

🚀 快速开始

# Clone the repository
git clone https://github.com/yourusername/wsg-courses-mcp.git
cd wsg-courses-mcp

# Create conda environment
conda env create -f environment.yml
conda activate wsg-courses-mcp-dev

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Place your certificates in certificates/
# - certificates/cert.pem
# - certificates/key.pem

# Run the server
python main.py

# Access the API documentation
# Open http://localhost:8000/docs

📦 先决条件

• Python 3.12+ （或Python 3.10+）
• WSG API证书: cert.pem 和 key.pem

- 从…获得 SSG-WSG开发者门户

• Git 用于版本控制
• 码头工人 （可选，用于容器化部署）
• 谷歌云SDK （可选，用于云运行部署）

系统要求

• 记忆：最低512MB，建议1GB
• 中央处理器：至少1芯，建议使用2+芯
• 存储：100MB用于应用程序+依赖关系
• 网络：与api.ssg-wsg.sg的HTTPS连接

🔧 安装

地方发展

选项1：康达（推荐）

# Create conda environment
conda env create -f environment-dev.yml

# Activate environment
conda activate wsg-courses-mcp-dev

# Copy environment template
cp .env.example .env

# Edit .env with your configuration

选项2：虚拟环境

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt

# Copy environment template
cp .env.example .env

# Edit .env with your configuration

Docker安装

# Build image
docker build -t wsg-courses-mcp:latest .

# Run container
docker run -p 8080:8080 `
  -v ${PWD}/certificates:/app/certificates:ro `
  --env-file .env `
  wsg-courses-mcp:latest

# Or use Docker Compose
docker-compose up -d

⚙️ 配置

创建 .env 文件：

BASE_URL=https://api.ssg-wsg.sg
CERT_PATH=certificates/cert.pem
KEY_PATH=certificates/key.pem
ENVIRONMENT=development
LOG_LEVEL=INFO
PORT=8000

证书设置

1. 从WSG开发者门户获取证书
2. 创建 certificates/ 目录
3. 复制 cert.pem 和 key.pem 到证书/
4. 确保证书未提交到版本控制

💻 用法

启动服务器

# Development (with auto-reload)
python main.py

# Production with Uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000

# Production with Gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

API终点

• Swagger用户界面: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• MCP端点: http://localhost:8000/mcp
• 健康检查: http://localhost:8000/health

请求示例

# Search courses
curl "http://localhost:8000/courses/directory?keyword=python&page_size=5"

# Get categories
curl "http://localhost:8000/courses/categories?keyword=training"

# Get popular courses
curl "http://localhost:8000/courses/directory/popular?page_size=10"

# Get course details
curl "http://localhost:8000/courses/directory/TGS-2020500330"

📚 API终点

🤖 MCP工具

AI代理可以通过MCP协议访问这些工具：

1. get_course_categories -搜索和浏览类别
2. get_course_tags -检索可用标签
3. 搜索_搜索_关键字 -按关键字查找课程
4. 搜索_搜索_标记 -按标签筛选课程
5. get_course_autocomplete -获取搜索建议
6. get_curse_子类别 -浏览子类别
7. get_course_details -获取详细的课程信息
8. 获取相关课程 -查找类似课程
9. get_popular_courses -发现热门课程
10. get_featured_courses -查看特色课程

🛠️ 发展

# Format code
black .
isort .

# Type checking
mypy .

# Linting
flake8 .

# Run all checks
black . ; isort . ; flake8 . ; mypy .

🧪 测试

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=. --cov-report=html

# Specific test file
pytest tests/test_unit_endpoints.py -v

# Integration tests
pytest tests/test_integration_mcp.py -v

# View coverage report
# Open htmlcov/index.html in browser

🚀 部署

本地部署

python main.py

Docker部署

docker-compose up -d

谷歌云运行

当前部署： https://wsg-courses-mcp-server-c2tuon4crq-uc.a.run.app

# Build and deploy
gcloud builds submit --tag gcr.io/job-rec-repo/wsg-courses-mcp-server

gcloud run deploy wsg-courses-mcp-server \
  --image gcr.io/job-rec-repo/wsg-courses-mcp-server \
  --region us-central1 \
  --allow-unauthenticated \
  --update-secrets="WSG_CERT_PATH=wsg-cert:latest,WSG_KEY_PATH=wsg-key:latest" \
  --set-env-vars="ENVIRONMENT=production,BASE_URL=https://api.ssg-wsg.sg"

详细部署说明见实施计划。

📊 监控

• 健康端点: /health 用于正常运行时间监控
• 日志：带时间戳的结构化日志记录
• 指标：请求计数、延迟、错误（在云运行中）
• 警报：为生产配置云监控

🔒 安全

• 从不将证书提交到版本控制(.pem 文件在 .gitignore)
• 使用Secret Manager进行云部署
• 证书作为只读卷装载
• 所有API请求都使用带有mTLS的HTTPS
• Pydantic模型的输入验证
• 全面的错误处理

报告安全问题：在GitHub上创建私人安全咨询

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing
3. 进行更改并添加测试
4. 运行测试： pytest tests/ -v
5. 格式代码： black . ; isort .
6. 承诺： git commit -m 'Add amazing feature'
7. 推： git push origin feature/amazing
8. 打开拉取请求

📝 许可证

MIT许可证-请参阅 许可证 文件

👥 作者

• 你的名字-

🙏 致谢

• 新加坡技能未来新加坡（SSG）和劳动力新加坡（WSG）
• FastAPI和FastAPI_mcp社区
• 模型上下文协议社区

📞 支持

• 问题:
• 实时API: https://wsg-courses-mcp-server-c2tuon4crq-uc.a.run.app/docs
• 文档：见实施计划 .github/prompts/

______________________________________________________________________

内置❤️ 新加坡教育和培训界