内容
植物园 MCP
**用于 AI 辅助 FreePBX 模块开发的本地化开发环境。**
植物园 MCP 是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为您的编码助手提供 FreePBX® 模块开发所需的环境、上下文和依赖项。
它打包了精选的文档、主题依赖项和可选的源代码仓库，以便模块工作可以立足于实际框架。
它是一个社区参考工具。 它 **不是** Sangoma 或 FreePBX 项目的官方软件或官方文档。
**作者：** [James Finstrom](https://github.com/jfinstrom)
## 捐赠
我不接受该项目的捐赠、赞助或直接付款。
如果您想间接支持我，可以查看 [Clearly IP](https://lyip.com/) 或 [14IP](https://www.14ip.com/)。他们 **不** 直接支持、赞助或认可该项目，但我的工资来自他们，养活我的家人。他们的持续成功对我个人有益。
---
## 这是什么（和不是什么）
| 植物园 MCP **是** | 植物园 MCP **不是** |
|-----------------|---------------------|
| 您本地运行的开发助手 MCP 服务器 | Sangoma 或 FreePBX 的官方产品 |
| 模块作者的本地化上下文 | 维基或论坛的替代品 |
| AGPL-3.0 下的免费软件 | 专有知识库 |
| 对商标生态系统的合理描述和引用 | 得到 Sangoma 或 FreePBX 项目的认可或赞助 |
该仓库旨在成为实用的、非官方的参考资料。
### 为什么是“植物园”？
植物园容纳了支持生物系统的环境和依赖项。 在这里，名称反映了目标：为 AI 助手提供 FreePBX 模块可靠工作所需的上下文、文档和源代码引用。
我们不运送青蛙。 我们运送栖息地。
---
## 快速开始
```bash
git clone https://github.com/jfinstrom/terrarium-mcp.git
cd terrarium-mcp
npm install
npm run build
```
### 连接到您的 MCP 客户端（stdio）
```json
{
"mcpServers": {
"terrarium-mcp": {
"command": "node",
"args": ["/absolute/path/to/terrarium-mcp/dist/index.js"]
}
}
}
```
- **VS Code / GitHub Copilot：** 将相同的服务器条目添加到您的工作区或用户 MCP 配置中，以便 Copilot Chat 可以发现它。
```json
{
"servers": {
"terrarium-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/terrarium-mcp/dist/index.js"]
}
}
}
```
将其保存在 `.vscode/mcp.json` 中以适用于当前工作区，或保存在用户 MCP 配置中以在 VS Code 中全局使用。
- **Cursor：** 设置 → MCP，或 `~/.cursor/mcp.json`
- **Claude Desktop：** `%APPDATA%\Claude\claude_desktop_config.json`（Windows）/ `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
在 `examples/` 中查看启动配置。
### 可选：克隆上游源代码仓库
对于 `search_sources` 和 `read_source_file` 工具：
```bash
./scripts/clone-sources.sh # Linux/macOS
.\scripts\clone-sources.ps1 # Windows
```
源代码较大，默认情况下被 gitignore。 48 个上下文文档在没有它们的情况下也能正常工作。
### 可选：HTTP 模式
```bash
npm run dev:http
# http://localhost:3100/sse (MCP)
#localhost:3100/health
```
---
## 您将获得的内容
| 层 | 内容 |
|-------|----------|
| **上下文 `context/` 中的 48 个 Markdown 主题，涵盖引导、BMO、钩子、拨号计划、API、打包等 |
| **清单** | `manifest/topics.json`，包含层、依赖项和主题索引 |
| **MCP 服务器** 客户端的工具、资源和提示 |
| **源代码**（可选） | 公共上游仓库的浅克隆，用于代码搜索 |
### MCP 工具
| 工具 | 目的 |
|------|---------|
| `list_topics` | 按层或关键词浏览主题 |
| `get_topic` | 主题的完整 Markdown |
| `search_context` | 搜索所有 48 个文档 |
| `suggest_learning_path` | 任务的主题顺序 |
| `search_sources` | 搜索克隆的 `sources/` |
| `read_source_file` | 读取带有行号的源文件 |
### MCP 提示
- `new-freepbx-module` - 脚手架工作流
- `debug-freepbx-module` - 结构化调试工作流
---
## 主题层级
| 层级 | 焦点 |
|------|-------|
| 1 | 引导、BMO 架构、模块生命周期 |
| 2 | `module.xml`、BMO 类、GUI、数据库 |
| 3 | AJAX、钩子、拨号计划、功能代码 |
| 4 | `fwconsole`、重载、备份、签名 |
| 5 | UCP、GraphQL、REST、FastAGI、测试 |
| 6 | 命名、样式、打包、贡献 |
---
## 许可证
**GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL-3.0-or-later）**
这是最具限制性的、被广泛认可的 **免费** 软件许可证。 简单来说：
- **使用它。** 从中学习并将其集成到您的工作流中。
- **分享改进。** 如果您分发修改后的代码或上下文，您必须在相同许可证下提供源代码。
- **网络使用计入。** 如果您将修改后的版本作为网络服务供用户交互使用，则适用 AGPL 义务。
- **不得将其作为专有软件重新授权。** 如果您分发或商业化派生作品，您必须遵守 AGPL。
上下文文档和服务器代码均为 AGPL-3.0-or-later。 `sources/` 中的第三方源代码克隆仍在其原始许可证下。
完整许可证文本：[LICENSE](---
## 商标
**FreePBX®** 是 **Sangoma Technologies** 的注册商标。
本项目中提到的所有其他商标、服务标志、产品名称和公司名称均为其各自所有者的财产。 对 FreePBX、Sangoma、Asterisk 或相关商标的引用 **仅为描述性和命名性合理使用**。
本项目 **不隶属于、未得到、未获得、也未被** Sangoma Technologies 或 FreePBX 项目以任何官方身份认可、支持或赞助。
---
## 免责声明
本项目与 Sangoma Technologies 无关，也未得到其认可或赞助。 任何对 FreePBX、Sangoma 或相关商标的引用仅用于描述性和合理使用目的。 不应推断出任何认可或支持。
**本项目也未得到、赞助或认可我的雇主或我曾关联的任何其他组织。** 它是一个个人副项目，而不是公司交付成果。
**请自担风险。** 植物园 MCP 按原样提供。 它可能不正确、不完整或随着上游更改而过时。
在将其用于生产电信系统之前，请与上游代码和文档验证行为。
---
## 仓库布局
```
terrarium-mcp/
├── context/ # 48 个基础主题文档（AGPL-3.0）
├── manifest/ # 机器可读的主题目录
├── src/ # MCP 服务器源代码（AGPL-3.0）
├── dist/ # 编译后的服务器（运行 npm run build 后）
├── scripts/ # 可选的源代码克隆助手
├── examples/ # MCP 客户端配置片段
├── SOURCE_AUDIT.md # 验证日志
└── LICENSE # AGPL-3.0
```
---
```bash
npm run dev # 通过 tsx 进行 stdio
npm run dev:http # HTTP/SSE 在 :3100
npm run build # 编译到 dist/
npm test # 集成测试（启动真实服务器，MCP 协议）
```
### 集成测试（非单元测试）
`npm test` **不** 在进程中导入服务器代码。 它：
1. **构建** `dist/index.js`
2. **启动** 服务器作为单独的操作系统进程（`node dist/index.js`）
3. **连接** 真实的 MCP `Client` 通过线路
4. **调用** 工具，读取资源，并针对实时服务器解析提示
| 套件 | 传输 | 镜像 |
|-------|-----------|---------|
| `test/integration/stdio-server.test.ts` | stdio | Cursor, Claude Desktop |
| `test/integration/http-server.test.ts` | HTTP + SSE | 托管 / 远程部署 |
`test/integration/scenarios.ts` 中的共享场景针对两种传输运行，因此行为保持一致。
测试通过 `.github/workflows/test.yml` 在推送/拉取请求到 `main` 时在 CI 中运行。
---
## 贡献
1. 在可能的情况下，以公共源代码为基础。
2. 在您验证或更正某些内容时，更新 `SOURCE_AUDIT.md`。
3. 保持非场，不要将其标记为任何官方认可。
4. 在推送之前运行 `npm run build`；stdio MCP 服务器不得在 stdout 上输出聊天内容。
欢迎拉取请求。
