Sign Language MCP API

手语MCP API🤟

用于学习模型上下文协议（MCP）与人工智能系统集成的教育性REST API

本项目旨在让学生了解：

• REST API设计和开发
• 发现端点的工作原理（类似于MCP工具发现）
• AI代理可以理解的自描述API
• 传统API与AI工具集成之间的联系
• 跨多种语言的手语基础

非常适合AI俱乐部、编程训练营或任何想了解API如何连接到大型语言模型（LLM）的人！

______________________________________________________________________

🎯 这个项目是什么？

这是一个 基于Flask-based REST API 它为三种手语中的常见单词提供手语描述：

• 国外 （澳大利亚手语）
• 联合参谋部后勤部 （日语手语）
• 是 （国际标志）

API演示了反映如何 模型上下文协议（MCP） 作品：

1. 发现 -查找可用的资源/工具
2. 自我描述 -描述自己的API
3. 结构化数据 -AI代理如何理解和使用工具

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.8或更高版本
• pip（Python包管理器）

安装与运行

# 1. Clone the repository (replace YOUR-USERNAME with your GitHub username)
git clone https://github.com/YOUR-USERNAME/sign-language-mcp-api.git
cd sign-language-mcp-api

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the API
python app.py

# Optional: Configure with environment variables
# FLASK_HOST=0.0.0.0 FLASK_PORT=8080 FLASK_DEBUG=False python app.py

API将于 http://127.0.0.1:5000 默认情况下为（localhost）。

环境变量（可选）：

• FLASK_HOST -要绑定的主机（默认值： 127.0.0.1，使用 0.0.0.0 对于所有接口）
• FLASK_PORT -端口号（默认值： 5000)
• FLASK_DEBUG -调试模式（默认： True，设置为 False 用于生产）

第一个API调用

在浏览器中尝试以下网址：

http://127.0.0.1:5000/                          # Welcome page
http://127.0.0.1:5000/api/v1/words              # See all available words
http://127.0.0.1:5000/api/v1/languages          # See supported languages
http://127.0.0.1:5000/api/v1/capabilities       # See ALL API capabilities
http://127.0.0.1:5000/api/v1/signs/hello        # Get "hello" in all languages
http://127.0.0.1:5000/api/v1/signs/hello/auslan # Get "hello" in Auslan only

______________________________________________________________________

📚 API端点文档

发现终点（MCP教学点！）

GET /api/v1/words

发现可用的单词

答复：

{
  "words": ["hello", "help", "please", "sorry", "thank_you"],
  "count": 5,
  "hint": "Use GET /api/v1/signs/{word} to get sign descriptions"
}

教学要点： 这就像MCP工具发现——在使用工具之前，先发现可用的工具！

______________________________________________________________________

GET /api/v1/languages

了解支持哪些手语

答复：

{
  "languages": [
    {"code": "auslan", "name": "Australian Sign Language"},
    {"code": "jsl", "name": "Japanese Sign Language"},
    {"code": "is", "name": "International Sign"}
  ],
  "count": 3,
  "hint": "Use language codes in GET /api/v1/signs/{word}/{language}"
}

教学要点： 类似于MCP描述工具的参数选项！

______________________________________________________________________

GET /api/v1/capabilities

META端点-API自我描述！

这是 最重要的终点 了解MCP概念！

答复包括：

• 完整的API说明
• 所有可用端点
• 每个端点的参数
• 示例用法
• 参数的可用值

教学要点： 在MCP中，服务器使用模式描述其功能。这个端点对我们的REST API做同样的事情！人工智能代理可以读取这个端点并了解如何使用整个API。

______________________________________________________________________

数据端点

GET /api/v1/signs/

获取所有语言中单词的符号描述

例子： GET /api/v1/signs/hello

答复：

{
  "word": "hello",
  "languages": {
    "auslan": {
      "language_full": "Australian Sign Language",
      "description": "Open hand, palm facing outward...",
      "handshape": "Open hand with fingers together",
      "movement": "Small arc outward from forehead",
      "facial_expression": "Friendly smile"
    },
    "jsl": { ... },
    "is": { ... }
  },
  "count": 3
}

______________________________________________________________________

GET /api/v1/signs//

获取特定语言中特定单词的符号

例子： GET /api/v1/signs/thank_you/auslan

答复：

{
  "word": "thank_you",
  "language": "auslan",
  "sign": {
    "language_full": "Australian Sign Language",
    "description": "Flat hand starts at chin, palm facing body...",
    "handshape": "Flat hand, fingers together",
    "movement": "Forward and downward from chin",
    "facial_expression": "Grateful smile"
  }
}

______________________________________________________________________

公用设施端点

GET /api/v1/health

运行状况检查-验证API是否正在运行

答复：

{
  "status": "healthy",
  "api_name": "Sign Language MCP API",
  "version": "1.0.0"
}

______________________________________________________________________

GET /

带欢迎消息和快速入门指南的根端点

______________________________________________________________________

🎓 MCP教学组

什么是MCP（模型上下文协议）？

MCP是一种允许AI模型（如ChatGPT、Claude）使用的协议 工具 和访问 资源将其视为人工智能的一种标准化方式：

1. 发现 有哪些可用的工具
2. 理解 如何使用每个工具
3. 执行 获取信息或执行操作的工具

此API如何展示MCP概念

关键见解

REST API和MCP工具在概念上相似：

• 两者都需要发现机制
• 两者都需要明确的能力描述
• 两者都需要处理输入并返回结构化输出
• 两者都受益于自我记录

这个API帮助学生在学习MCP之前理解传统的REST，使MCP概念更容易掌握！

______________________________________________________________________

🎯 人工智能俱乐部学习路径（3周课程）

第1周：了解REST API

目标： 使用此项目了解API的工作原理

活动：

1. 在本地克隆并运行API
2. 使用浏览器和 curl
3. 了解JSON响应
4. 读取代码 app.py -关注评论
5. 修改数据库以添加新单词

练习： 在所有三种语言中添加“再见”标志 database.py

______________________________________________________________________

第2周：发现和自我描述

目标： 了解API如何自我描述

活动：

1. 学习 /api/v1/capabilities 端点
2. 将其与中的MCP模式进行比较 mcp/sign_language_mcp.json
3. 了解发现端点的重要性
4. 创建一个简单的Python脚本，调用API

练习： 编写一个Python脚本：

• 呼叫 /api/v1/words 发现可用单词
• 对于每个单词，调用 /api/v1/signs/{word} 获取描述
• 打印格式化的报告

______________________________________________________________________

第3周：MCP集成概念

目标： 将REST API知识连接到MCP

活动：

1. 学习 mcp/sign_language_mcp.json 文件
2. 将MCP工具定义与API端点进行比较
3. 讨论人工智能将如何使用此API
4. 探索真实的MCP服务器（如果可用）

练习：

• 为这个API设计一个MCP工具包装器
• 编写人工智能代理如何发现和使用此API的伪代码
• 讨论：“什么能让人工智能更容易使用API？”

______________________________________________________________________

🚢 部署选项

安全说明： 该项目运行Flask debug=True 促进地方发展和学习。对于生产部署，您应该： - 集 debug=False 在 app.py - 使用像Gunicorn或uWSGI这样的生产WSGI服务器 - 添加适当的环境变量处理 - 启用HTTPS/TLS加密

选项1：回复（对学生来说最容易）

1. 创建新的Repl，从GitHub导入
2. Replit自动检测Python并安装需求
3. 点击“运行”-就是这样！

选项2：渲染（免费层）

1. 将您的GitHub仓库连接到Render
2. 选择“Web服务”
3. 构建命令： pip install -r requirements.txt
4. 启动命令： gunicorn app:app （添加 gunicorn 到requirements.txt）

选项3：铁路（现代和便捷）

1. 连接GitHub仓库
2. 铁路自动检测Python
3. 将生产WSGI服务器添加到requirements.txt
4. 推送时自动部署

选项4:PythonAnywhere（教育友好型）

1. 将文件上传到PythonAnywhere
2. 使用Flask设置web应用程序
3. 配置WSGI文件以指向 app.py

______________________________________________________________________

🔧 如何扩展此项目

添加更多单词

编辑 database.py 并将条目添加到 SIGN_DATABASE:

"goodbye": {
    "auslan": { ... },
    "jsl": { ... },
    "is": { ... }
}

添加更多语言

1. 添加语言 SUPPORTED_LANGUAGES 在 database.py
2. 为每个单词添加该语言的符号描述
3. 更新中的MCP架构枚举 mcp/sign_language_mcp.json

添加更多功能

学生项目的想法：

• 为标志添加图像/视频
• 添加难度评级
• 添加类别（问候语、情感、问题）
• 添加用户收藏夹系统
• 添加测验/练习模式端点
• 添加搜索功能
• 添加发音指南

连接到真实数据库

将内存中的字典替换为：

• SQLite（最简单）
• PostgreSQL（生产就绪）
• MongoDB（如果你想要NoSQL体验）

______________________________________________________________________

📖 手语资源

想了解更多关于手语的知识吗？

• 奥斯兰 Signbank -澳大利亚手语
• 日语手语词典 -JSL资源
• 世界聋人联合会 -国际标志信息
• 手语101 -学习资源

______________________________________________________________________

🤝 贡献

这是一个教育项目！欢迎捐款：

• 添加更多单词和符号
• 改进文档
• 添加更多教学示例
• 修复bug
• 添加测试

______________________________________________________________________

📝 许可证

MIT许可证-免费用于教育目的！

______________________________________________________________________

🙏 致谢

为AI俱乐部教育目的而创建。特别感谢：

• 全球手语社区
• 开源贡献者
• 学习API和AI集成的学生

______________________________________________________________________

💡 问题或议题？

在GitHub上打开一个问题，或者在你的AI俱乐部会议上提问！

快乐学习！ 🎉🤟