AI导哈

文档上下文管理工具

一个用于技术文档管理的工具，通过本地存储和AI可访问的上下文文件，提高文档的可访问性和维护效率。

  • by EdwardAngert
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 EdwardAngert/reformatters-knowledge-base

使用说明

重整模式知识库

项目状态和背景

该存储库代表了对如何使技术文档更易于人类和人工智能工具访问的探索，特别是对于没有专门技术作者的团队。

我们正在解决的问题

挑战： 大型代码库需要良好的文档，但是：

  • 人工智能工具难以应对大型文档网站（上下文限制、信息分散）
  • 当文档跨越多个位置的数百页时，“只阅读文档”失败
  • 没有技术编写人员的团队需要一种轻量级的方法来维护高质量的文档
  • AI助手在会话之间失去上下文并重复错误

我们想要的：

  • 易于人类导航和人工智能解析的文档
  • AI可以引用的持久上下文（架构、模式、风格决策）
  • 会话内存，使AI不会忘记以前的工作
  • 无需复杂的基础设施即可实现团队范围内的可访问性

我们尝试了什么：MCP服务器方法

我们最初构建了一个MCP（模型上下文协议）服务器，通过AI可访问的工具为重新格式化器文档提供服务。

什么不起作用：

  • 远程部署限制： Claude Desktop仅支持本地stdio连接，使得Railway部署无法用于主要用例
  • 循环依赖关系： 数据集工具需要主格式化程序包，这违背了单独存储库的目的
  • 克服复杂性： 需要单独的仓库、部署基础设施和维护负担
  • 架构不匹配： 内置的HTTP/SSE服务器无法被预期客户端使用

关键见解： MCP还不够成熟，无法在整个团队范围内进行远程访问。目前，它最适合本地个人开发人员使用。

当前方向：Sidecar上下文+插件

基于其他项目中经过验证的模式(共享文档kb, 文档代理技能)，我们正在朝着：

结构：

reformatters/
├── docs/                      # Public documentation (MkDocs → GitHub Pages)
│   ├── .context/             # Sidecar context files (for AI)
│   │   ├── architecture.md   # How reformatters works
│   │   ├── patterns.md       # Common code patterns
│   │   ├── style-guide.md    # Documentation conventions
│   │   └── session-notes.md  # AI session memory
│   ├── guides/
│   ├── playbooks/
│   └── examples/
└── .claude/skills/
    └── load-context.py       # Auto-loads context for AI

它是如何工作的：

  1. 公共文档位于主仓库中（单一真实来源）
  2. 边车 .context/ 文件提供精心策划的AI上下文
  3. 插件/技能在会话开始时加载上下文
  4. 人工智能既有通用的方法论，也有特定项目的知识
  5. 会议记录在工作会议之间保留决策

为什么这样更好：

  • ✅ 单一存储库（无同步问题）
  • ✅ 适用于任何AI工具（非MCP特定）
  • ✅ 零基础设施成本
  • ✅ 人类可读、git版本化的上下文
  • ✅ 团队可以通过编辑markdown做出贡献
  • ✅ 生产使用中经过验证的模式

当前状态

此存储库包含优秀的文档内容（指南、剧本、示例），这些内容将按照上述sidecar模式迁移到主重新格式化器存储库中。

传统MCP服务器文档

以下部分记录了MCP服务器的实现。此方法已弃用，但保留以供参考。

原始描述

MCP（模型上下文协议）服务器，作为 重整器 代码库。这是一个支持和文档资产，可帮助工程师和支持团队轻松贡献文档、剧本和指南。

这是什么？

此存储库提供：

  1. 知识库：人类贡献的文档（指南、剧本、示例）
  2. MCP服务器：用于文档生成、代码探索和支持的AI可访问工具
  3. 两种访问模式:
    • 本地：直接在您的计算机上运行Claude Desktop
    • 远程：部署到Railway以实现团队范围内的HTTP访问

快速开始

用于本地开发（Claude Desktop）

  1. 克隆并安装：

    git clone https://github.com/dynamical/reformatters-knowledge-base.git
cd reformatters-knowledge-base
uv sync

  2. 配置Claude桌面：

    编辑您的配置文件：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %APPDATA%\Claude\claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

    添加此配置（将路径替换为您的路径）：

    {
  "mcpServers": {
    "reformatters-kb": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/reformatters-knowledge-base",
        "run",
        "reformatters-kb-stdio"
      ]
    }
  }
}

  3. 重新启动克劳德桌面 完全（退出并重新打开）

  4. 测试IT -问克劳德：

    • “列出所有知识”
    • “回填搜索指南”
    • “搜索剧本以排除故障”

用于远程部署（铁路）

看 部署.md 用于部署到Railway以实现团队范围内的访问。

供贡献者使用（添加文档）

  1. 克隆此存储库：

    git clone https://github.com/dynamical/reformatters-knowledge-base.git
cd reformatters-knowledge-base

  2. 添加文档：

    # Add a guide
echo "# My Guide" > knowledge/guides/my-guide.md

# Add a playbook
echo "# Troubleshooting XYZ" > knowledge/playbooks/troubleshooting/xyz-issue.md

# Commit and push
git add knowledge/
git commit -m "Add documentation for XYZ"
git push

  3. 文档可通过MCP服务器自动获取！

发展

项目结构

reformatters-knowledge-base/
├── knowledge/              # Human-contributed content
│   ├── guides/            # User guides
│   ├── playbooks/         # Support runbooks
│   ├── examples/          # Code examples
│   └── architecture/      # Architecture docs
├── src/mcp_server/        # MCP server implementation
│   ├── server.py         # HTTP/SSE server (for Railway)
│   ├── stdio_server.py   # Stdio server (for Claude Desktop)
│   ├── config.py         # Configuration
│   └── tools/            # MCP tool implementations
├── tests/                 # Tests
└── deploy/                # Deployment configs

两种服务器模式

此项目支持两种部署模式：

1.标准模式（本地克劳德桌面）

  • 使用： reformatters-kb-stdio 命令
  • 传输：标准输入/标准输出
  • For：本地开发和测试
  • 配置：克劳德桌面 command 和 args

2.HTTP模式（远程铁路）

  • 使用： uvicorn mcp_server.server:app
  • 传输：HTTP与服务器发送事件（SSE）
  • 适用于：团队范围内的远程访问
  • 终点： /sse 和 /messages/

在本地测试HTTP服务器

要在本地测试铁路部署：

# Install dependencies
uv sync

# Run the HTTP server
uv run uvicorn mcp_server.server:app --reload --port 8000

# Test endpoints
curl http://localhost:8000/health  # Should return {"status":"healthy"}

注： 此HTTP服务器是 不 由Claude Desktop使用。Claude Desktop直接使用stdio服务器。

运行测试

uv run pytest

知识库内容

📚 综合文件（17份文件）

指南 （6份文件）：

  • 入门指南 -安装和第一步
  • 数据集集成指南 -逐步整合
  • 常见问题 -60+常见问题和答案
  • 常见错误 -30多种错误模式及其解决方案
  • CLI备忘单 -快速命令参考
  • 架构概述 -系统设计和概念

剧本 （5份文件）：

  • 回填失败 -诊断和修复回填问题
  • AWS凭据错误 -解决权限问题
  • 验证失败 -数据验证故障排除
  • 内存和资源问题 -OOM、磁盘、CPU问题
  • 运行回填 -完整的操作指南

示例 （3个代码示例）：

  • 最小模板配置 -新数据集的起点
  • 最小区域作业 -处理逻辑示例
  • 自定义验证程序 -数据验证示例

技术作家：参见 技术_作者_指南.md 获取全面的文档路线图和模板。

能力

MCP工具

知识库搜索

  • search_guides -查找相关用户指南
  • search_playbooks -查找支持剧本
  • list_all_knowledge -浏览整个知识库

数据集工具 （需要安装格式化程序包）

  • list_datasets -列出所有格式化程序数据集
  • get_dataset_info -获取详细的数据集信息
  • get_dataset_implementation -显示实施细节

文档工具

  • generate_dataset_readme -自动生成数据集文档
  • generate_cli_command -生成CLI命令

部署

看 部署.md 铁路部署说明。

HTTP服务器可以部署到Railway，以实现团队范围内的远程访问。请注意，Claude Desktop无法连接到远程HTTP MCP服务器，它只支持基于本地stdio的服务器。

贡献

看 贡献.md 关于以下方面的指导方针：

  • 添加指南
  • 制作剧本
  • 贡献示例
  • 使用Claude Desktop进行测试

许可证

麻省理工学院

相关 MCP