Skip to content

feat(mcp): migrate backend from Hermes to LibreChat#27

Open
itsablabla wants to merge 4 commits intomainfrom
devin/1776095989-librechat-backend
Open

feat(mcp): migrate backend from Hermes to LibreChat#27
itsablabla wants to merge 4 commits intomainfrom
devin/1776095989-librechat-backend

Conversation

@itsablabla
Copy link
Copy Markdown
Owner

@itsablabla itsablabla commented Apr 13, 2026

Summary

Replaces the custom Hermes Agent backend with LibreChat as the headless API backend. LibreChat provides native MCP support (118 Nextcloud tools via Streamable HTTP), multi-model switching, built-in context compression, and an agent framework — eliminating the custom agent loop, context overflow bugs, and per-tool middleware that required constant patching.

What changed

PHP Proxy (OpenClawService.php + AgentController.php)

  • Default URL: http://localhost:18789 (Hermes) → http://LibreChat:3080 (Docker DNS on nextcloud-aio network)
  • API path: /v1/chat/completions/api/agents/v1/chat/completions (LibreChat's OpenAI-compatible agents endpoint)
  • Model: hermes-agentagent_jada_nextcloud (LibreChat agent configured with Gemini 2.5 Flash + 118 MCP tools)
  • Health endpoint now queries LibreChat's /api/agents/v1/models and reports engine: librechat

Vue Frontend (ChatView.vue)

  • Added handling for standard OpenAI delta.tool_calls format (LibreChat sends tool calls this way instead of Hermes's custom event: hermes.tool.progress)
  • Tool names stripped of _mcp_serverName suffix for display (e.g., nc_webdav_list_directory_mcp_nextcloudnc_webdav_list_directory)
  • Backward compat: legacy Hermes hermes.tool.progress events still parsed

Metadata

  • Version bumped to 0.4.0
  • info.xml description updated to reflect LibreChat architecture

Infrastructure (already deployed on server)

  • LibreChat Docker stack (5 containers) running on 83.228.213.100
  • LibreChat connected to nextcloud-aio Docker network (DNS name: LibreChat)
  • Agent agent_jada_nextcloud created in MongoDB with sys__all__sys_mcp_nextcloud (all 118 tools)
  • Nextcloud MCP server connected via http://nextcloud-mcp-server:8000/mcp (Streamable HTTP)
  • iptables MASQUERADE rule for librechat_default network (external API access)

Review & Testing Checklist for Human

  • Send a chat message in https://next.garzaos.online/apps/jadaagent/ and verify streaming response works
  • Trigger a tool call — ask "List my Nextcloud files" and verify the tool call appears in the right panel with the correct name (not the raw _mcp_nextcloud suffix)
  • Verify health display — footer should show "Gemini (via LibreChat) · 118 tools" and greeting should show "118 tools across 1 servers"
  • Check mobile — ensure chat input remains visible on iOS Safari during streaming (regression check from v0.2.6 fix)
  • Verify conversation persistence — send a message, reload the page, confirm the conversation + response survived

Notes

  • The LibreChat API key is stored in Nextcloud's app config (openclaw_token), not hardcoded in PHP
  • LibreChat's tool name format is toolName_mcp_serverName (server name LAST, not first) — this was the root cause of the MCP tool parsing bug in the previous session
  • The sys__all__sys_mcp_nextcloud tool reference tells LibreChat to load ALL tools from the nextcloud MCP server, instead of listing each of the 118 tools individually
  • Hermes container is still running but no longer used by Jada Agent — can be stopped after verifying LibreChat works

Link to Devin session: https://app.devin.ai/sessions/f4e16f12bfa34fc6bdc3d73a833a5d91
Requested by: @itsablabla


Open with Devin

- PHP proxy now calls LibreChat's OpenAI-compatible API at /api/agents/v1/chat/completions
- Model changed from 'hermes-agent' to 'agent_jada_nextcloud' (LibreChat agent with 118 MCP tools)
- Default URL changed to http://LibreChat:3080 (Docker DNS on nextcloud-aio network)
- Vue SSE parser handles standard OpenAI delta.tool_calls format (LibreChat)
- Tool names stripped of _mcp_serverName suffix for display (e.g. nc_webdav_list_directory_mcp_nextcloud → nc_webdav_list_directory)
- Backward compat: legacy hermes.tool.progress events still parsed
- Version bumped to 0.4.0
- Updated info.xml description to reflect LibreChat architecture
@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

devin-ai-integration[bot]

This comment was marked as resolved.

Fixes Devin Review finding: /_mcp_[^_]+$/ fails for server names
containing underscores (e.g. my_server). Changed to /_mcp_.+$/ which
greedily matches everything after the _mcp_ delimiter.
devin-ai-integration[bot]

This comment was marked as resolved.

- getSkills(): return empty list (LibreChat has no skills endpoint)
- getModels(): proxy to LibreChat's /api/agents/v1/models
- getConfig(): return stub with engine info (config managed via LibreChat admin UI)
- getSessions(): return empty list (LibreChat manages sessions internally)

Fixes Devin Review finding: these 4 methods still used Hermes-specific
/api/v1/* paths that don't exist on LibreChat.
devin-ai-integration[bot]

This comment was marked as resolved.

- AdminSettings.php: default URL http://localhost:18789 → http://LibreChat:3080
- SettingsController.php: same default URL update
- templates/admin.php: placeholder URL + heading updated to LibreChat

Fixes Devin Review finding: admin UI showed stale Hermes defaults.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant