Libre Chat MCP

Librechatmcp-librechat管理服务器

一个全面的模型上下文协议（MCP）服务器，用于管理LibreChat实例，提供代理管理、MCP服务器管理、模型查询和用户特定文件存储的工具。

特性

🤖 代理管理

• 创建和配置代理 -构建具有特定指令和功能的自定义AI代理
• 列出和查询代理 -浏览和检索代理配置
• 更新代理 -修改现有代理设置
• 删除代理 -不再需要时删除代理
• 类别和工具 -查询可用的代理类别和工具

🔌 MCP服务器管理

• 察看连接信息 -获取有关MCP服务器配置的信息
• 服务器状态 -检查MCP服务器的运行状况和可用性
• 工具发现 -列出服务器上可用的MCP工具

🎯 模型管理

• 模型列表 -跨端点查询可用的AI模型

📁 用户文件存储

• 隔离存储 -每个用户都有私人的、隔离的文件存储
• 文件操作 -上传、列出、读取、修改和删除文件
• Markdown注释 -使用自动创建格式化笔记 .md 扩展
• 语义搜索 -使用RAG API按内容搜索文件
• 永久存储 -文件在pod重启后仍然存在
• 自动索引 -为语义搜索建立索引的文件

快速开始

本地开发

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export LIBRECHAT_API_BASE_URL="http://localhost:3080/api"
export LIBRECHAT_EMAIL="your-email@example.com"
export LIBRECHAT_PASSWORD="your-password"
export RAG_API_URL="http://localhost:8000"

# Run the server
python main.py

测试

# Run unit tests
pytest tests/test_file_storage.py -v

# Run integration tests (requires RAG API)
RAG_API_URL=http://localhost:8000 pytest tests/test_rag_integration.py -v -m integration

# Run OAuth integration tests (requires LibreChat credentials)
export TEST_LIBRECHAT_EMAIL='your-email@example.com'
export TEST_LIBRECHAT_PASSWORD='your-password'
pytest tests/test_oauth_integration.py::test_oauth_flow_docker -v

# Run OAuth tests in production
export PRODUCTION_HOST='https://chat.example.com'
pytest tests/test_oauth_integration.py::test_oauth_flow_production -v

# Run critical OAuth configuration test (prevents error redirects)
pytest tests/test_oauth_integration.py::test_oauth_configuration_prevents_error_redirect -v

# Or use the test runner script
./tests/run_oauth_tests.sh docker      # Test Docker environment
./tests/run_oauth_tests.sh production  # Test production environment
./tests/run_oauth_tests.sh health     # Quick health check (no credentials)
./tests/run_oauth_tests.sh config     # Validate OAuth config (CRITICAL - prevents error redirects)
./tests/run_oauth_tests.sh all        # Run all tests

# Run all tests
pytest tests/ -v

Git挂钩

LibreChatMCP包括用于自动质量检查的git挂钩。当你提交或推送代码时，钩子会自动运行。

安装

当您运行根存储库的安装脚本时，钩子会自动安装：

# From root repository
./scripts/install-git-hooks.sh

或在此子模块中手动安装挂钩：

cd LibreChatMCP
chmod +x .git/hooks/pre-commit .git/hooks/pre-push

预提交钩子

预提交钩子在每次提交之前运行快速测试：

• 代码检查: ruff check 或 flake8
• 格式化: ruff format --check 或 black --check
• 类型检查: mypy （如果已配置，则无阻塞）
• 单元测试: pytest tests/ -v -m "not integration" --tb=short
• OAuth配置验证: pytest tests/test_oauth_integration.py::test_oauth_configuration_prevents_error_redirect -v

手动运行：

./scripts/run-fast-tests.sh

预推钩

预推钩在推之前会进行集成测试：

• 集成测试: pytest tests/ -v -m integration
• OAuth集成测试: pytest tests/test_oauth_integration.py -v （需要凭据）
• Docker构建测试：成功验证Dockerfile构建
• Dockerfile Lint: hadolint Dockerfile （如果可用）

手动运行：

./scripts/run-integration-tests.sh

旁路选项

需要时绕过挂钩：

# Skip pre-commit hook
git commit --no-verify

# Skip pre-push hook
git push --no-verify

# Skip hooks in CI/CD
export SKIP_HOOKS=true

部署到Kubernetes

# Build and push Docker image
docker build -t ghcr.io/simonvanlaak/librechatmcp:latest .
docker push ghcr.io/simonvanlaak/librechatmcp:latest

# Deploy with Helm
cd ../../helm/librechat
helm upgrade --install librechat . \
  --set librechatmcp.storage.enabled=true \
  --set librechatmcp.ragApiUrl=http://librechat-rag-api:8000

可用工具

代理管理

MCP服务器管理

模型管理

文件存储

建筑

graph TB
    A[LibreChat User] -->|HTTP + X-User-ID| B[LibreChatMCP Server]
    B -->|FastMCP| C[Tool Registry]
    
    C --> D[Agent Tools]
    C --> E[MCP Tools]
    C --> F[Model Tools]
    C --> G[File Storage Tools]
    
    D -->|HTTP| H[LibreChat API]
    E -->|HTTP| H
    F -->|HTTP| H
    
    G -->|Filesystem| I[User Storage
/storage/user_id/]
    G -->|HTTP| J[RAG API]
    J --> K[(VectorDB)]
    
    B -.->|Middleware| L[User Context]
    L -.-> G

配置

环境变量

LibreChat连接：

• LIBRECHAT_API_BASE_URL -librechat API端点（默认值： http://api:3080/api)
• LIBRECHAT_EMAIL -API身份验证的管理员电子邮件
• LIBRECHAT_PASSWORD -API身份验证的管理员密码

文件存储：

• STORAGE_ROOT -文件存储的根目录（默认： /storage)
• RAG_API_URL -RAG API终点（默认值： http://librechat-rag-api:8000)
• CHUNK_SIZE -嵌入的文本块大小（默认值： 1500)
• CHUNK_OVERLAP -块之间的重叠（默认值： 100)

服务器：

• HOST -服务器主机（默认值： 0.0.0.0)
• PORT -服务器端口（默认值： 8000)

LibreChat集成

添加 librechat.yaml:

mcpServers:
  librechat_mcp:
    type: streamable-http
    url: http://librechat_mcp:3002/mcp
    headers:
      X-User-ID: "{{LIBRECHAT_USER_ID}}"
    serverInstructions: |
      LibreChat Management Assistant with File Storage:
      - Create, manage, and query LibreChat agents and MCP servers
      - Personal file storage: upload, list, read, modify, delete files
      - Create markdown notes with create_note (auto-formats with title)
      - Semantic file search powered by RAG API
      - All files are private and isolated per user
    timeout: 600000

项目结构

LibreChatMCP/
├── main.py                       # FastMCP server entry point
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Container image definition
├── setup.cfg                     # Pytest configuration
├── middleware/
│   ├── __init__.py
│   └── user_context.py          # Extract user_id from headers
├── tools/
│   ├── __init__.py
│   ├── agent.py                 # Agent management tools
│   ├── model_context_protocol.py # MCP server tools
│   ├── models.py                # Model query tools
│   ├── file_storage.py          # File storage operations
│   └── auth.py                  # LibreChat authentication
└── tests/
    ├── __init__.py
    ├── test_file_storage.py     # File storage unit tests
    └── test_rag_integration.py  # RAG API integration tests

用户隔离（文件存储）

文件存储实现了严格的用户隔离：

• 存储路径： /storage/{user_id}/{filename}
• 文件ID: user_{user_id}_{filename} （用于vectordb）
• 元数据筛选： 所有搜索都会自动筛选 user_id
• 基于标头的身份验证： 用户身份来自 X-User-ID 标题（由LibreChat设置）

用户上下文提取

服务器从中提取用户上下文 X-User-ID LibreChat发送的HTTP标头。这是通过以下方式实现的：

1. ASGI中间件 (middleware/user_context.py)：拦截HTTP请求并提取 X-User-ID 头球
2. 上下文变量 (contextvars)：为每个请求的用户上下文提供线程安全存储
3. 文件存储集成：所有文件操作都会自动使用当前用户上下文

实施细节：

• 使用Python contextvars 用于线程安全、按请求的用户上下文存储
• 中间件提取 X-User-ID 来自传入请求的标头
• 模板字符串如下 {{LIBRECHAT_USER_ID}} 被忽略（视为无用户上下文）
• 这允许初始化在没有用户上下文的情况下工作
• 每次请求后都会自动清除用户上下文
• 如果缺少用户上下文，文件存储操作将引发 RuntimeError
• 初始化和其他非文件存储操作在没有用户上下文的情况下工作正常

注： FastMCP不会公开其底层ASGI应用程序，因此中间件是通过一个试图访问FastMCP内部应用程序的包装器应用的。如果无法访问应用程序，服务器将退回直接运行FastMCP（不使用中间件），这意味着用户上下文提取可能无法工作。在这种情况下，文件存储操作将失败，并出现身份验证错误。

验证：

• 检查服务器日志中是否有“使用用户上下文中间件启动LibreChatMCP服务器”消息
• 如果您看到“警告：用户上下文中间件不可用”，则回退模式处于活动状态
• LibreChat UI的测试文件操作-如果中间件处于活动状态，它们应该可以工作

依赖项

• fastmcp -MCP服务器框架
• 请求： -LibreChat API的HTTP客户端
• aiofiles -异步文件I/O操作
• httpx -用于RAG API的异步HTTP客户端
• pytest & pytest异步 -测试框架

用例

代理管理

"Create an agent called 'Code Reviewer' that reviews Python code"
"List all available agents"
"Update the Code Reviewer agent to also check for security issues"
"Delete the old Test Agent"

文件存储和注释

"Create a note titled 'Project Ideas' with my brainstorming list"
"Upload my meeting_notes.txt file"
"Search my files for 'quarterly report'"
"List all my files"
"Read the Project_Ideas.md file"

MCP服务器管理

"What MCP servers are available?"
"Check the status of all MCP servers"
"List all tools available through MCP"

GitHub操作秘密

此存储库使用GitHub Actions进行自动化CI/CD。必须在存储库设置中配置以下机密（设置→ 秘密和变量→ 行动）：

必需的秘密

• PARENT_REPO_TOKEN -个人访问令牌（PAT） repo 在成功推送图像后，触发父存储库（TheMaryAnne）工作流的作用域。此令牌必须具有触发权限 repository_dispatch 父存储库中的事件。

如何生成令牌

1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
2. 使用生成新令牌 repo 范围
3. 将其添加为名为的秘密 PARENT_REPO_TOKEN 在这个存储库的秘密中

自动化部署流程

当代码被推送到 main 分支：

1. 测试运行（如有）
2. Docker镜像已构建并推送到GitHub容器注册表
3. 父存储库（TheMaryAnne）会自动触发以更新子模块引用和部署

贡献

这是Hetzner Cloud上TheMaryAnne项目LibreChat部署的一部分。

许可证

看 许可证 项目根目录中的文件。