内容
# 组织文档
**您团队的记忆库 — 由 Git 仓库支持的 MCP 服务器。**
[](./LICENSE)
[](https://github.com/shashank-sn/organisation.md/actions/workflows/ci.yml)
`organisation.md` 将任何 GitHub 仓库转变为您的组织的持久上下文层。任何兼容 MCP 的 AI 工具（Claude Code、Cursor 等）都可以**读取**、**搜索**和**提出更新**您的团队共享上下文 — 无需数据库，无需托管服务，无需离开您的 GitHub 账户。
---
## 工作原理
1. **Fork** 此仓库到您的 GitHub 组织。
2. **编辑** `organisation.md` 文件，包含您的团队身份、项目、决策和偏好。
3. **运行** MCP 服务器 — 您的 AI 代理连接并自然地读取/写入上下文。
所有更改都经过**拉取请求** — 您的团队审查和合并它们。Git 提供版本历史、分支和访问控制开箱即用。
## 快速入门
### 1. 生成个人访问令牌
前往 [github.com/settings/tokens](https://github.com/settings/tokens) 并生成一个具有 `repo` 作用域的**经典令牌**。复制令牌 — 您将在下一步中使用它。
### 2. 使用 npx 运行（推荐）
```bash
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your-github-username-or-org
export GITHUB_REPO=organisation.md
npx @shashank-sn/organisation-md
```
就这样。MCP 服务器以 stdio 模式启动，您的 AI 代理可以连接。
### 3. 或克隆并本地运行
```bash
git clone https://github.com/your-org/organisation.md.git
cd organisation.md
npm install
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your-github-username-or-org
export GITHUB_REPO=organisation.md
npx tsx src/server.ts
```
### 4. 连接到您的 AI 代理
服务器通过 stdio 通信 MCP。配置您的 AI 工具以启动它：
**Claude Code** — 添加到您的 `.mcp.json`：
```json
{
"mcpServers": {
"organisation.md": {
"command": "npx",
"args": ["@shashank-sn/organisation-md"],
"env": {
"GITHUB_TOKEN": "ghp_...",
"GITHUB_OWNER": "your-org",
"GITHUB_REPO": "organisation.md"
}
}
}
}
```
**Cursor / Continue / 其他 MCP 主机** — 指向相同的命令和环境变量。
## 工具
| 工具 | 描述 |
|------|-------------|
| `read_org` | 从 GitHub 仓库读取完整的 `organisation.md` 文件 |
| `read_section` | 按标题读取特定章节（例如，“团队”，“决策”） |
| `update_section` | 提出对章节的更新 — 创建拉取请求 |
| `search_context` | 在 `organisation.md` 和所有 `context/` 文件中搜索 |
| `propose_change` | 提出对仓库中任何文件的更改 — 创建拉取请求 |
| `list_context_files` | 列出 `context/` 目录中的所有文件 |
| `import_file` | 将 txt、md 或 docx 文件导入知识库 |
| `add_info` | 通过自然语言添加信息 — 自动检测章节 |
| `remove_info` | 删除匹配描述的信息 |
| `check_roles` | 检查基于 Git 的角色和代码所有者 |
| `check_permissions` | 检查是否可以添加/删除/批准/合并 |
| `configure_codeowners` | 更新 `.github/codeowners` 以进行团队访问控制 |
| `report_bug` | 自动检测区域并提交 GitHub 问题 |
| `suggest_feature` | 建议功能或改进作为 GitHub 问题 |
## 仓库结构
```
organisation.md/
├── organisation.md # 规范的组织上下文文件
├── context/ # 支持的上下文文件
│ ├── README.md
│ ├── projects.md # 详细的项目信息
│ ├── architecture.md # 系统架构
│ └── people.md # 团队成员和角色
├── src/ # MCP 服务器源代码（TypeScript）
│ ├── server.ts # 入口点
│ ├── github/ # Octokit 包装器（文件，Git API）
│ ├── content/ # Markdown 解析器和模板
│ ├── tools/ # MCP 工具实现
│ └── resources/ # MCP 资源模板
├── docs/ # 文档
│ ├── quickstart.md # 完整的设置指南
│ ├── agent-prompt.md # AI 代理的提示模板
│ └── example-flows.md # 常见的流程
├── scripts/
│ └── build-site.mjs # GitHub Pages 构建脚本
├── .github/workflows/
│ ├── ci.yml # CI：推送/PR 时进行类型检查 + 测试
│ └── pages.yml # GitHub Pages 部署
├── strategy.md # 产品策略
├── license # MIT
└── README.md
```
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `github_token` | 是 | 具有 `repo` 作用域的 GitHub 个人访问令牌 |
| `github_owner` | 是 | 拥有仓库的 GitHub 用户名或组织 |
| `github_repo` | 是 | 仓库名称（默认为 `organisation.md`） |
## 自定义
1. **编辑 `organisation.md`** — 用您团队的实际身份、项目和决策替换模板内容。
2. **添加 `context/` 文件** — 创建额外的 Markdown 文件以提供更深入的上下文（架构文档、运行手册等）。
3. **Fork 和重命名** — 将仓库 fork 到您的组织并更新环境变量以指向您的 fork。
## 开发
```bash
npm install
npm run dev # 具有热重载的开发服务器
npm test # 运行测试
npm run typecheck # TypeScript 检查
npm run build # 编译 TypeScript
npm run build:site # 在本地构建 GitHub Pages 站点
```
## 许可证
MIT — fork 它，使用它，发布它。参见 [license](./license)。
