Canvas LMS模型上下文协议
一种服务器实现,使Smithery能够在不进行身份验证的情况下列出工具,同时将身份验证推迟到工具执行。
延迟加载身份验证
此服务器遵循Smithery关于“延迟加载”身份验证的建议:
-
工具列表:The
/api/tools端点允许任何客户端(包括Smithery)列出可用工具,而不需要身份验证。这对发现至关重要。 -
工具执行:只有在实际执行工具时才需要身份验证凭据。凭据在执行时传递到请求正文中。
这种方法确保:
- Smithery可以显示工具列表,而无需用户预先提供身份验证
- 通过在访问受保护的资源时要求适当的身份验证来维护安全性
- API密钥和敏感凭据仅在绝对必要时使用
API终点
公共端点(无需身份验证)
GET /api/tools-列出所有可用工具GET /api/tools/:id-获取特定工具的详细信息
受保护的端点(请求中需要身份验证)
POST /api/tools/:id/execute-执行特定工具
工具执行请求格式```json
{
"parameters": {
"key1": "value1",
"key2": "value2"
},
"authentication": {
"apiKey": "your-canvas-api-key",
"domain": "your-canvas-domain.instructure.com"
}
}
## 响应格式
### 成功响应```json
{
"success": true,
"result": {
// Tool-specific result data
}
}
错误响应```json
{
"success": false,
"error": "Error message describing what went wrong"
}
## 可用工具
1. **获取课程**
- 身份证件: `get-courses`
- 描述:从Canvas LMS检索课程
- 参数:
- `limit` (可选):返回的最大课程数
1. **获取作业**
- 身份证件: `get-assignments`
- 描述:检索特定课程的作业
- 参数:
- `courseId` (必填):课程ID
## 发展
1. 安装依赖项: `npm install`
1. 构建项目: `npm run build`
1. 启动服务器: `npm start`
## 码头工人
为了便于部署,我们提供了Docker配置:```bash
docker build -t canvas-mcp .
docker run -p 3000:3000 canvas-mcp
Canvas LMS MCP服务器
此服务器充当后端代理和实用程序层,用于与Canvas LMS实例交互,提供处理后的数据,供语言模型(LLM)或其他应用程序使用。
它允许获取课程详细信息、作业信息(包括描述和附加文件链接/内容)、讨论主题,并从Canvas上托管的PDF文件中提取文本。
设置
- 克隆存储库(如果适用):```bash
git clone
cd CanvasMCP
1. **安装依赖关系:**```bash
npm install
- 配置环境变量:
创建一个.env在项目根目录中创建文件,并添加以下变量。将占位符值替换为实际的Canvas凭据。```env
Standard Canvas Instance
CANVAS_API_URL=https://your-canvas-domain.instructure.com
CANVAS_API_TOKEN=your_standard_canvas_api_token
AWS Hosted Canvas Instance (if applicable)
AWS_CANVAS_API_URL=https://your-aws-canvas-domain.instructure.com
AWS_CANVAS_API_TOKEN=your_aws_canvas_api_token
Server Port (Optional, defaults to 3000)
PORT=3000
1. **运行服务器:**
- 对于开发(自动重新加载): `npm run dev`
- 生产: `npm start`
服务器将在以下时间运行 `http://localhost:PORT` (例如。, `http://localhost:3000`).
## API终点
所有端点都需要在 `.env` 文件。
### 健康检查
- **得到/**
- **说明:** 检查服务器是否正在运行。
- **例子:**```bash
curl http://localhost:3000/
- 成功响应:
Canvas MCP Server is running!(内容类型:text/html)
标准画布API(/api/...)
用途 CANVAS_API_URL 和 CANVAS_API_TOKEN.
-
GET/api/courses/:courseId
-
说明: 获取特定课程的详细信息。
- 路径参数:
:courseId(数字):课程的ID。- 例子:```bash
curl http://localhost:3000/api/courses/12345
- **成功响应(示例):** `{ "id": 12345, "name": "Introduction to Programming", ... }`
- **GET/api/courses/:courseId/作业**
- **说明:** 获取特定课程的作业列表。
- **路径参数:**
- `:courseId` (数字):课程的ID。
- **例子:**```bash
curl http://localhost:3000/api/courses/12345/assignments
-
成功响应(示例):
[ { "id": 987, "name": "Assignment 1", ... }, ... ] -
GET/api/作业/:课程ID/:作业ID
-
说明: 获取特定任务的详细信息。
- 路径参数:
:courseId(数字):课程的ID。:assignmentId(number):作业的ID。- 例子:```bash
curl http://localhost:3000/api/assignments/12345/987
- **成功响应(示例):** `{ "id": 987, "name": "Assignment 1", "description": "...", ... }`
- **GET/api/作业/:课程ID/:作业ID/提交**
- **说明:** 获取特定任务的提交详细信息(需要适当的权限)。
- **路径参数:**
- `:courseId` (数字):课程的ID。
- `:assignmentId` (number):作业的ID。
- **例子:**```bash
curl http://localhost:3000/api/assignments/12345/987/submissions
-
成功响应(示例):
[ { "user_id": 101, "grade": "A", ... }, ... ] -
GET/api/作业/:课程ID/:作业ID/描述
-
说明: 获取作业描述以及提取的附件链接。
- 路径参数:
:courseId(数字):课程的ID。:assignmentId(number):作业的ID。- 例子:```bash
curl http://localhost:3000/api/assignments/12345/987/description
- **成功响应(示例):**```json
{
"description": "
Please read the attached file.
Instructions.pdf
",
"linked_files": [
{
"link_text": "Instructions.pdf",
"file_id": "44827106",
"download_url": "https://your-canvas-domain.instructure.com/files/44827106/download?download_frd=1"
}
]
}
-
GET/api/discussion/:courseId/:discussionTopicId
-
说明: 获取特定讨论主题的详细信息。
- 路径参数:
:courseId(数字):课程的ID。:discussionTopicId(number):讨论主题的ID。- 例子:```bash
curl http://localhost:3000/api/discussions/12345/678
- **成功响应(示例):** `{ "id": 678, "title": "Week 1 Discussion", "message": "...", ... }`
### PDF工具(`/api/pdf/...`)
用途 `CANVAS_API_URL` 和 `CANVAS_API_TOKEN`.
- **POST/api/pdf/提取文本**
- **说明:** 使用Canvas的文件ID从Canvas下载PDF文件并提取文本内容。
- **请求正文:** `application/json````json
{
"fileId": 44827106
}
- 例子:```bash
curl -X POST \
http://localhost:3000/api/pdf/extract-text \
-H 'Content-Type: application/json' \
-d '{"fileId": 44827106}'
- **成功响应(示例):**```json
{
"text": "This is the extracted text content from the PDF...\nPage 2 content..."
}
- 错误响应:
400 Bad Request:缺失或无效fileId.401 Unauthorized / 404 Not Found:API令牌无效、权限不足或找不到文件ID(有关Canvas API的详细信息,请查看服务器日志)。500 Internal Server Error:服务器配置错误(缺少.env变量)、下载失败或解析PDF失败。
成绩
通过提交端点检索单个作业的成绩信息:
- GET/api/作业/:课程ID/:作业ID/提交
- 说明: 获取特定作业的提交详细信息,包括成绩(
grade,score)每次提交。 - (请参阅标准画布API下的完整说明)
AWS画布API(/api/aws/...)
用途 AWS_CANVAS_API_URL 和 AWS_CANVAS_API_TOKEN.
这些端点镜像标准Canvas API端点,但以 .env 文件。
-
GET/api/aws/courses/:courseId
-
GET/api/aws/课程/:课程ID/作业
-
GET/api/aws/作业/:courseId/:assignmentId
-
GET/api/aws/作业/:课程ID/:作业ID/描述
-
(注意:此处返回的文件下载链接将指向AWS Canvas实例)
-
GET/api/aws/作业/:课程ID/:作业ID/提交 (提供AWS等级)
(使用和响应类似于上面的标准API端点,但使用 /api/aws 前缀和AWS Canvas凭据。)
错误处理
服务器包含一个全局错误处理程序。大多数源自Canvas API或内部处理的错误将返回带有 error 对象包含 message 字段:json
{
"error": {
"message": "Specific error details here..."
}
}
有关更详细的堆栈跟踪和调试信息,请查看服务器控制台日志。
