starred/karakeep

Fork 0

mirror of https://github.com/karakeep-app/karakeep.git synced 2026-04-25 07:56:05 +03:00

[GH-ISSUE #1965] Request: Add HTTP Streamable or SSE Transport for MCP Service Node #1220

New issue

Open

opened 2026-03-02 11:55:51 +03:00 by kerem · 5 comments

kerem commented

2026-03-02 11:55:51 +03:00

Owner

Originally created by @mwnu on GitHub (Sep 21, 2025).
Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/1965

Describe the feature you'd like

Currently, KaraKeep only supports Command-line Based Transport (STDIO) for MCP service nodes. This limitation makes it incompatible with certain web platforms and serverless environments where STDIO isn't available or practical.

Suggested Solution:
Please consider adding support for either:

HTTP Streamable transport (long-polling style)
Server-Sent Events (SSE) transport
This would enable KaraKeep to work in more environments, particularly:

Web-based platforms
Serverless functions
Browser extensions
Any environment where persistent STDIO isn't available

Describe the benefits this would bring to existing Karakeep users

Use Cases:

Running KaraKeep as a microservice in cloud environments
Web-based frontends communicating with KaraKeep backend
Platforms that require HTTP-based communication protocols
Additional Context:
Many modern platforms (especially web-based ones) are moving away from STDIO-based communication in favor of HTTP-based protocols. SSE would be particularly suitable as it's:

Simple to implement
Works over standard HTTP
Naturally supports streaming data
Has good browser support

Can the goal of this request already be achieved via other means?

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundamental request

Additional context

I tried to use Karakeep as an MCP client in n8n, but n8n doesn't support it.

Originally created by @mwnu on GitHub (Sep 21, 2025). Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/1965 ### Describe the feature you'd like Currently, KaraKeep only supports Command-line Based Transport (STDIO) for MCP service nodes. This limitation makes it incompatible with certain web platforms and serverless environments where STDIO isn't available or practical. Suggested Solution: Please consider adding support for either: HTTP Streamable transport (long-polling style) Server-Sent Events (SSE) transport This would enable KaraKeep to work in more environments, particularly: Web-based platforms Serverless functions Browser extensions Any environment where persistent STDIO isn't available ### Describe the benefits this would bring to existing Karakeep users Use Cases: Running KaraKeep as a microservice in cloud environments Web-based frontends communicating with KaraKeep backend Platforms that require HTTP-based communication protocols Additional Context: Many modern platforms (especially web-based ones) are moving away from STDIO-based communication in favor of HTTP-based protocols. SSE would be particularly suitable as it's: Simple to implement Works over standard HTTP Naturally supports streaming data Has good browser support ### Can the goal of this request already be achieved via other means? No ### Have you searched for an existing open/closed issue? - [x] I have searched for existing issues and none cover my fundamental request ### Additional context I tried to use Karakeep as an MCP client in n8n, but n8n doesn't support it.

kerem added the

feature request

status/untriaged

labels

2026-03-02 11:55:51 +03:00

kerem commented

2026-03-02 11:55:52 +03:00

Author

Owner

@grimwiz commented on GitHub (Sep 26, 2025):

I've been working on this... I've been "vibe coding" with ChatGPT's codex to add openapi compatibility.
See the code under https://github.com/grimwiz/karakeep/tree/main/apps/mcp

@grimwiz commented on GitHub (Sep 26, 2025): I've been working on this... I've been "vibe coding" with ChatGPT's codex to add openapi compatibility. See the code under https://github.com/grimwiz/karakeep/tree/main/apps/mcp

kerem commented

2026-03-02 11:55:52 +03:00

Author

Owner

@grimwiz commented on GitHub (Sep 27, 2025):

I enquired about the difficulty to add those two features, the response from my AI helper is given below, so I'm tempted to keep tweaking my openapi interface, but if you'd like me to continue investigating please make a note below and I'll have a go:

Current API architecture
The MCP CLI only allows two transport modes today: "stdio" (wired through StdioServerTransport) and "openapi" (a plain Node http.createServer that emits JSON once per request). Extending this enumeration, the CLI parser, and the branch in run() is the first hurdle for any new transport.

The HTTP implementation immediately serializes a payload with sendJson(...) and closes the socket, so there is no infrastructure for holding connections open or pushing incremental messages.

Tool handlers fetch Karakeep data through an openapi-fetch client (createKarakeepClient) and build the entire result set before returning; there is no streaming pipeline to reuse downstream.

HTTP streamable (long‑polling) transport
Implementing a long‑polling mode would require a new transport branch alongside stdio/openapi, plus server code that can park requests until the MCP server has data to flush. The existing createServer callback assumes a one-shot response, so you would need to introduce connection bookkeeping, request queues, and a translation layer that maps the MCP server’s message envelopes into “next chunk” payloads while respecting timeouts and retries. None of that scaffolding exists today, so the work is moderate-to-high: new transport mode plumbing in the CLI, a dedicated handler that cooperates with McpServer.connect, and state management for multiple outstanding polls.

Server‑Sent Events (SSE)
Supporting SSE raises the bar further. The current helpers always terminate the response (res.end(JSON.stringify(...))), so you would need a parallel code path that sets Content-Type: text/event-stream, keeps sockets alive, emits heartbeat/comments, and tears connections down cleanly on client disconnects. You would also need a transport adapter that converts MCP messages into SSE events and handles backpressure/ordering, something the existing request/response tooling does not address. Expect additional coordination so that tool handlers can signal partial progress or incremental records if you want to make SSE worthwhile, because they currently return only fully-buffered results.

Overall difficulty
Both features will require non-trivial new infrastructure around the MCP server: augmenting the transport selection surface, building persistent-connection HTTP handlers, and introducing message queues or streaming adapters on top of the synchronous tool implementations. Long‑polling is somewhat simpler (single response per poll) but still medium-to-high effort; SSE adds persistent streaming semantics and is high effort given the current codebase.

@grimwiz commented on GitHub (Sep 27, 2025): I enquired about the difficulty to add those two features, the response from my AI helper is given below, so I'm tempted to keep tweaking my openapi interface, but if you'd like me to continue investigating please make a note below and I'll have a go: Current API architecture The MCP CLI only allows two transport modes today: "stdio" (wired through StdioServerTransport) and "openapi" (a plain Node http.createServer that emits JSON once per request). Extending this enumeration, the CLI parser, and the branch in run() is the first hurdle for any new transport. The HTTP implementation immediately serializes a payload with sendJson(...) and closes the socket, so there is no infrastructure for holding connections open or pushing incremental messages. Tool handlers fetch Karakeep data through an openapi-fetch client (createKarakeepClient) and build the entire result set before returning; there is no streaming pipeline to reuse downstream. HTTP streamable (long‑polling) transport Implementing a long‑polling mode would require a new transport branch alongside stdio/openapi, plus server code that can park requests until the MCP server has data to flush. The existing createServer callback assumes a one-shot response, so you would need to introduce connection bookkeeping, request queues, and a translation layer that maps the MCP server’s message envelopes into “next chunk” payloads while respecting timeouts and retries. None of that scaffolding exists today, so the work is moderate-to-high: new transport mode plumbing in the CLI, a dedicated handler that cooperates with McpServer.connect, and state management for multiple outstanding polls. Server‑Sent Events (SSE) Supporting SSE raises the bar further. The current helpers always terminate the response (res.end(JSON.stringify(...))), so you would need a parallel code path that sets Content-Type: text/event-stream, keeps sockets alive, emits heartbeat/comments, and tears connections down cleanly on client disconnects. You would also need a transport adapter that converts MCP messages into SSE events and handles backpressure/ordering, something the existing request/response tooling does not address. Expect additional coordination so that tool handlers can signal partial progress or incremental records if you want to make SSE worthwhile, because they currently return only fully-buffered results. Overall difficulty Both features will require non-trivial new infrastructure around the MCP server: augmenting the transport selection surface, building persistent-connection HTTP handlers, and introducing message queues or streaming adapters on top of the synchronous tool implementations. Long‑polling is somewhat simpler (single response per poll) but still medium-to-high effort; SSE adds persistent streaming semantics and is high effort given the current codebase.

kerem commented

2026-03-02 11:55:52 +03:00

Author

Owner

@javydekoning commented on GitHub (Oct 25, 2025):

SSE MCP as part of Karakeep seems like the best path forward here. Home Assistant took this route:

https://www.home-assistant.io/integrations/mcp_server/
https://github.com/home-assistant/core/tree/dev/homeassistant/components/mcp_server

And so have many others.

@javydekoning commented on GitHub (Oct 25, 2025): SSE MCP as part of Karakeep seems like the best path forward here. Home Assistant took this route: https://www.home-assistant.io/integrations/mcp_server/ https://github.com/home-assistant/core/tree/dev/homeassistant/components/mcp_server And so have many others.

kerem commented

2026-03-02 11:55:52 +03:00

Author

Owner

@mareklesko commented on GitHub (Nov 7, 2025):

I believe SSE is deprecated as per here: https://mcp-framework.com/docs/Transports/sse/.
Can you try to implement streamable HTTP instead?

@mareklesko commented on GitHub (Nov 7, 2025): I believe SSE is deprecated as per here: https://mcp-framework.com/docs/Transports/sse/. Can you try to implement streamable HTTP instead?

kerem commented

2026-03-02 11:55:52 +03:00

Author

Owner

@hyxl520 commented on GitHub (Jan 9, 2026):

我也在期待这个功能，karakeep作为一个部署的web服务，有一个支持流式HTTP的 MCP服务还是一个很棒的想法。基于目前karakeep已经拥有的openAPI有可能做一MCP的适配吗

@hyxl520 commented on GitHub (Jan 9, 2026): 我也在期待这个功能，karakeep作为一个部署的web服务，有一个支持流式HTTP的 MCP服务还是一个很棒的想法。基于目前karakeep已经拥有的openAPI有可能做一MCP的适配吗

kerem referenced this issue

2026-03-02 11:59:15 +03:00

[PR #1348] [MERGED] feat: position highlight menu based on device type #1803

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/karakeep#1220

No description provided.

Rows
Columns