内容
# 工具列表
您的Moodle仪表盘，可供AI使用。
FastMCP服务器将Moodle课程、作业、成绩、测验、论坛、公告和日历事件作为MCP工具、资源和提示公开。
`moodle-mcp-srv`是一个独立项目。它与Moodle Pty Ltd无关，也不受其支持或赞助。
## 状态
- 项目状态：预发布1.0公共预览版。
- Python：3.13+。
- Moodle兼容性：尽力而为；站点支持取决于启用的Moodle Web服务功能。
- API稳定性：MCP工具名称和响应模式可能会在1.0之前发生变化。
- 支持：通过GitHub问题报告漏洞和功能请求；通过私信报告安全漏洞。
## 安全模型
- Moodle仍然是授权的源头。
- Moodle功能可用性检查是设置指南，而不是授权系统。
- 使用最小权限的Moodle Web服务令牌。
- 服务器不需要您的Moodle用户名或密码。
- MCP客户端可以看到工具和资源返回的Moodle数据。
- 默认情况下，写入工具设置为`dry_run=True`；实际写入需要明确的用户确认和`reason`。
- 未经身份验证和反向代理控制，不得公开暴露HTTP传输。
- 不要提交实时Moodle日志、固定数据、课程名称、成绩、提交内容或用户数据。
## 非目标
- 这不是官方Moodle产品。
- 这不是Moodle插件。
- 这不会绕过Moodle权限。
- 这不会存储Moodle凭证。
- 这不会提供托管的SaaS。
- 这不能保证与每个Moodle插件或自定义Web服务函数的兼容性。
## 安装
```sh
uv sync
cp .env.example .env
```
将以下内容设置为操作系统环境变量，或放入`.env` / `.env.local`中：
```sh
MOODLE_API_URL=https://moodle.example.edu/webservice/rest/server.php
MOODLE_API_TOKEN=your_token
```
优先级为操作系统环境变量，然后是`.env.local`，然后是`.env`。
将`moodle.example.edu`替换为您的Moodle门户主机。如果您的门户是`https://moodle.example.edu`，则API URL通常为：
```sh
MOODLE_API_URL=https://moodle.example.edu/webservice/rest/server.php
```
要找到令牌，请登录Moodle并检查：
```text
https://moodle.example.edu/user/managetoken.php
```
一些Moodle站点隐藏或禁用自助服务令牌。在这种情况下，请向Moodle管理员请求一个用于您的帐户的Web服务令牌。
设置凭证后快速连接检查：
```sh
uv run moodle-mcp ping
```
设置诊断：
```sh
uv run moodle-mcp doctor
uv run moodle-mcp doctor --json
```
通过stdio运行：
```sh
uv run moodle-mcp
```
通过HTTP运行：
```sh
uv run moodle-mcp serve --http --host 127.0.0.1 --port 8000
```
检查本地MCP表面：
```sh
uv run moodle-mcp inspect
```
已发布包使用：
```sh
uvx --from moodle-mcp-srv moodle-mcp
```
参见`examples/`获取VS Code、Zed、Claude Desktop、Claude Code、Codex、Gemini CLI、OpenCode、Factory Droid和Pi Code的MCP客户端代码段。
## 工具表面
服务器为Moodle上下文公开意图级工具和只读`moodle://`资源。运行：
```sh
uv run moodle-mcp inspect
uv run moodle-mcp doctor
```
`doctor`检查配置、Moodle连接、站点信息、预期的Web服务函数和功能可用性。
## 开发
```sh
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg
uv run ruff format
uv run ruff check
uv run ty check
uv run basedpyright
uv run lint-imports
uv run bandit -c pyproject.toml -r src main.py
uv run deptry .
uv run pip-audit
uv run pre-commit run gitleaks --all-files
uv run pytest
MOODLE_MCP_RUN_LIVE_TESTS=1 uv run pytest tests/test_live_moodle_tools.py -q
uv run pytest -n auto # 可选并行运行
```
可选MCP安全扫描：
```sh
uvx mcp-scan@latest inspect
```
项目布局：
```text
src/moodle_mcp/server.py FastMCP合成根
src/moodle_mcp/tools/ 按域划分的工具注册
src/moodle_mcp/resources/ 只读 moodle:// 上下文
src/moodle_mcp/prompts/ 可重用的Moodle工作流程
src/moodle_mcp/api/ 按域划分的Moodle工具实现
src/moodle_mcp/moodle/ Moodle REST客户端
src/moodle_mcp/models/ 类型化的工具响应形状
src/moodle_mcp/config/ 设置和日志记录
docs/agents/ 面向代理的文档
docs/human/ 面向人类的文档
```
## 发布说明
参见`CHANGELOG.md`。
## 路线图
参见`ROADMAP.md`。
## 安全
参见`SECURITY.md`和`docs/security/threat-model.md`。
## 许可证
Apache-2.0。参见`LICENSE`。
## 适用于代理
- 从`get_site_info`开始获取Moodle站点/版本元数据，然后使用`get_my_courses`发现已注册的课程。
- 在可用时，优先使用`moodle://`资源获取只读上下文。
- 默认情况下，写入工具设置为`dry_run=True`；传递`dry_run=False`仅在明确的用户确认后，并附上`reason`。
- 默认情况下，工具跨课程，如果它们接受`course_ids`。
- 使用`course_ids`缩小作业、成绩、测验和公告查询的范围。
- 使用`CONTEXT-MAP.md`查找规范术语，然后更改工具名称或响应形状。
- Moodle的时间戳是Unix时间戳，除非存在`_iso`字段。
