使用说明

🧠 存储库知识库-远程MCP服务器

AI驱动的代码智能系统 它通过模型上下文协议（MCP）将您的本地存储库与Claude Desktop连接起来。存储、搜索和分析有关代码库的结构化知识。

🚀 新现在使用 可流式传输的HTTP 运输（官方推荐的协议） FastMCP 为了简化部署！

🎯 这是什么？

A. 远程MCP服务器 即：

🗄️ 商店关于代码文件的结构化知识
🔍 搜索通过摘要、依赖关系和标签
🧠 分析文件和组件之间的关系
🤝 合并与Claude Desktop无缝对接

体系结构

┌──────────────────┐         ┌─────────────────────┐
│  Claude Desktop  │ ◄─────► │  Filesystem MCP     │
│   (Local AI)     │         │  (Read local files) │
└────────┬─────────┘         └─────────────────────┘
         │
         │ Streamable HTTP (Single Endpoint!)
         ▼
┌─────────────────────────────────────────────┐
│     DigitalOcean App Platform ($5/mo)       │
│  ┌─────────────────────────────────────┐    │
│  │  Repository Knowledge Base (FastMCP)│    │
│  │  • Streamable HTTP on /mcp          │    │
│  │  • Stateless deployment             │    │
│  │  • 8 powerful tools                 │    │
│  └──────────────┬──────────────────────┘    │
└─────────────────┼───────────────────────────┘
                  │
┌─────────────────▼────────────────────────┐
│     Supabase PostgreSQL (FREE!)          │
│  • 500 MB database storage               │
│  • SSL/TLS encryption                    │
│  • Automatic backups                     │
│  • Connection pooling                    │
└──────────────────────────────────────────┘

为什么是流式HTTP？

✅ 单端点 (/mcp)而不是多个端点
✅ 无状态 -非常适合云平台
✅ 官方标准 -SSE正在被弃用
✅ 更简单 -配置更少，调试更容易

✨ 特性

🔧 8强大的工具

工具	说明
`index_file`	索引单个文件的知识
`index_batch`	高效地索引多个文件
`search_knowledge`	通过代码进行语义搜索
`get_file_context`	获取完整的文件信息
`find_related`	查找相关文件
`search_by_type`	按文件类型过滤（二头肌、C#、Python等）
`get_stats`	知识库统计
`analyze_dependencies`	依赖图分析

📂 支持的文件类型

基础设施：二头肌、Terraform、Helm、YAML
后端：C#、Python、JavaScript、TypeScript
开发运维：PowerShell、Bash、Dockerfile
配置：JSON、ENV文件
文档：Markdown

🏷️ 技术类别

基础设施即代码
后端开发
前端开发
DevOps自动化
测试
文档
配置

🚀 快速开始

先决条件

Supabase账户 (免费PostgreSQL) - 必需
DigitalOcean帐户(获得200美元的免费积分)
GitHub账号
已安装Claude Desktop（支持MCP）
Python 3.11+

1.克隆和设置

git clone https://github.com/YOUR_USERNAME/repository-knowledge-base.git
cd repository-knowledge-base

# Copy environment template
cp .env.example .env

# Edit .env with your Supabase credentials
nano .env

2.设置数据库（2分钟）

在以下位置创建项目https://supabase.com/dashboard
从以下位置获取连接字符串： 设置→ 数据库→ 连接字符串→ URI

复制PostgreSQL连接字符串（带pooler的事务模式）：

postgresql://postgres.xxx:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres

更新 DATABASE_URL 在你的 .env 文件

3.部署到DigitalOcean

将代码推送到GitHub
首选https://cloud.digitalocean.com/apps
创建应用程序→ 选择您的GitHub仓库
添加 加密的 环境变量：
- DATABASE_URL -您的Supabase连接字符串
- MCP_SECRET_KEY -生成方式： openssl rand -hex 32
- LOG_LEVEL - INFO
- ALLOWED_ORIGINS - https://claude.ai
部署！

您的应用程序将在以下网址提供： https://your-app.ondigitalocean.app

4.连接克劳德桌面

对于使用Claude Pro/Max/Team/Enterprise的用户：

转到克劳德桌面→ 设置→ 连接器→ 添加自定义连接器

输入您的MCP端点URL：

https://your-app.ondigitalocean.app/mcp

对于没有Pro计划的用户（使用本地代理）：

编辑： ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/repository/repos"
      ]
    },
    "repository-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app.ondigitalocean.app/mcp"
      ]
    }
  }
}

重新启动克劳德桌面 完全（Cmd+Q/文件→ 退出并重新打开）。

寻找🔨 锤子图标确认您的服务器已连接！

📖 用法示例

索引文件

Hey Claude, use the filesystem MCP to read /repository/azure-iac/main.bicep 
and index it in the repository-knowledge server.

克劳德将：

使用文件系统MCP在本地读取文件
提取关键信息（资源、依赖关系等）
使用Streamable HTTP存储在远程知识库中

搜索知识

Search the repository-knowledge for "Azure storage configuration"

退货：

相关文件
摘要
关键要素
依赖项

分析依赖关系

Analyze dependencies for /repository/IntakeAPI/Services/AuthService.cs

退货：

直接依赖关系
依赖项（依赖于此文件的内容）
依赖深度

获取统计数据

Get stats from repository-knowledge

退货：

索引的文件总数
文件类型（二头肌、C#、Python等）
按存储库列出的文件
按技术分类的文件
上次索引时间戳

🗂️ 项目结构

repository-knowledge-base/
├── main.py                    # FastMCP server with Streamable HTTP
├── database.py                # SQLAlchemy database layer
├── models.py                  # Pydantic models
├── config.py                  # Configuration management
├── requirements.txt           # Python dependencies (with FastMCP)
├── Procfile                   # DigitalOcean runtime config
├── app.yaml                   # App Platform specification
├── .env.example               # Environment template
├── README.md                  # This file
└── LICENSE                    # MIT License

🔧 配置

环境变量

变量	描述	必填
`DATABASE_URL`	大写PostgreSQL连接字符串	✅ 是的
`MCP_SECRET_KEY`	安全密钥	✅ 是的
`ALLOWED_ORIGINS`	CORS来源（逗号分隔）	否（默认值： `https://claude.ai`)
`LOG_LEVEL`	日志记录级别	否（默认值： `INFO`)
`RATE_LIMIT_PER_HOUR`	API费率限制	否（默认值： `100`)
`MAX_FILE_SIZE_MB`	要索引的最大文件大小	否（默认值： `10`)

Supabase连接字符串格式

postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

来自： Supabase仪表板→ 设置→ 数据库→ 连接字符串→ URI（事务模式）

📊 数据库模式

`file_index` 表格

列	类型	描述
`id`	整数	主键
`path`	字符串（500）	完整文件路径（唯一）
`repo`	字符串（100）	存储库名称
`file_type`	字符串（50）	文件类型枚举
`technology`	字符串（50）	技术类别
`summary`	文本	文件用途摘要
`key_elements`	JSON	重要元素（数组）
`dependencies`	JSON	文件依赖关系（数组）
`dependents`	JSON	依赖文件（数组）
`tags`	JSON	可搜索标签（数组）
`content_hash`	字符串（64）	用于更改检测的内容哈希
`indexed_at`	DateTime	索引时间戳
`file_metadata`	JSON	附加元数据

指标：

idx_repo_filetype （repo，file_type）
idx_technology （技术）
idx_indexed_at （索引_at）
唯一约束 path

🛣️ API终点

端点	方法	描述
`/`	GET	服务器信息
`/health`	GET	使用统计数据进行健康检查
`/mcp`	职位	MCP可流式HTTP端点
`/docs`	GET	FastAPI自动生成文档

💰 成本细分

总计：$5/月

资源	成本/月	你得到什么
Supabase PostgreSQL	$0	500 MB存储空间、SSL、备份、池
数字海洋应用平台	$5	Python应用程序托管，SSL证书
总计	$5	完整的AI代码智能！ 🎉

免费等级限制（Supabase）

500 MB数据库存储
无限制的API请求
2 GB带宽
50 MB文件存储空间
7天备份保留期

足够容纳约50000个索引文件！

🧪 发展

在本地运行

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL="your-supabase-connection-string"
export MCP_SECRET_KEY="your-secret-key"

# Run server
python main.py

# Server runs on: http://localhost:8000
# MCP endpoint: http://localhost:8000/mcp
# Health check: http://localhost:8000/health

测试终点

# Health check
curl http://localhost:8000/health

# Server info
curl http://localhost:8000/

# API docs (Swagger UI)
open http://localhost:8000/docs

本地测试MCP

# Install MCP inspector
pip install mcp-inspector

# Test your server
mcp-inspector http://localhost:8000/mcp

🆘 故障排除

“连接被拒绝”或“超时”

检查：

✅ 您的Supabase项目状态是否为“活动”？
✅ 你更换了吗 [YOUR-PASSWORD] 在连接字符串中？
✅ 连接字符串的格式是否正确？
✅ 你在用 池化器 连接（端口6543）？

测试连接：

psql "postgresql://postgres:password@aws-0-region.pooler.supabase.com:6543/postgres"

“密码验证失败”

解决方案：

前往Supabase→ 设置→ 数据库
点击“重置数据库密码”
使用新密码更新DATABASE_URL
重新部署您的DigitalOcean应用程序

DigitalOcean中的“健康检查失败”

检查日志：

Apps → Your App → Runtime Logs

查找数据库连接错误或缺少的环境变量。

Claude Desktop未显示工具

检查：

✅ 完全重新启动Claude Desktop（退出并重新打开）
✅ 寻找🔨 克劳德的锤子图标
✅ 检查克劳德桌面日志： ~/Library/Logs/Claude/ （Mac）
✅ 验证您的MCP端点是否可访问： curl https://your-app.ondigitalocean.app/health

🔄 从SSE迁移到流式HTTP

如果你有旧的SSE版本，以下是变化：

旧（SSE）：

# Multiple endpoints
@app.get("/sse")  # SSE connection
Mount("/messages/", sse_transport.handle_post_message)  # Message handler

新（流式HTTP）：

# Single endpoint
app.mount("/mcp", mcp.streamable_http_app())  # Everything handled here!

优点：

✅ 1个端点，而不是2个
✅ 无状态（更适合云）
✅ 配置更简单
✅ 官方标准

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
提交拉取请求

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙏 致谢

人类MCP -模型上下文协议
FastMCP -高级MCP框架
Supabase -PostgreSQL数据库平台
快速API -现代Python web框架
数字海洋 -云基础设施

📚 额外资源

MCP文件 -MCP官方文件
FastMCP文档 -FastMCP文档
流式HTTP规范 -运输规范

📞 支持

🐛 问题： GitHub问题
💬 讨论： GitHub讨论

内置❤️ Malcon Albuquerque为Emperion项目撰写

技术支持： FastMCP+超级数据库（PostgreSQL）+数字海洋（托管）+人工MCP

🚀 现在有了流式HTTP——MCP的未来！