Torvian.eu/chatbot
Watch
1
0
Fork
You've already forked chatbot
 0
Code Issues Pull requests Projects Releases 12 Packages Wiki Activity Actions

Epic: NF.EA1 - Local MCP Servers #121

New issue
Closed
opened 2025-11-16 21:34:45 +00:00 by rwachters · 0 comments
rwachters commented 2025-11-16 21:34:45 +00:00 (Migrated from github.com)

Description

As a user, I want the LLM to be able to call local tools via the Model Context Protocol (MCP), so that the LLM can access real-time data and perform actions in the external world (such as searching the web, accessing local files, controlling GitHub repos, etc.).

This epic covers the end-to-end implementation for configuring, managing, and executing tools from local MCP servers running on a user's machine.

Acceptance Criteria

MCP Server Configuration

  • The user can configure their own local (STDIO) MCP servers with a name, command, arguments, and environment variables.
  • Environment variables are encrypted client-side for security.
  • The user can configure auto-start (autoStartOnEnable, autoStartOnLaunch) and auto-stop (autoStopAfterInactivitySeconds) behavior.
  • The user can set default tool enablement for new sessions (toolsEnabledByDefault).

MCP Server Management

  • The user can test the connection to an MCP server.
  • The user can discover tools from an MCP server, which persists them to the database.
  • The user can refresh the list of tools from an MCP server (adding new, updating changed, removing deleted).
  • MCP servers can be started and stopped from within the application, with their status tracked.

Data Persistence

  • MCP server configurations are stored locally on the client machine using SQLDelight.
  • The server stores a minimal record (id, userId) for linkage purposes.
  • MCP tools are stored in the central ToolDefinitionTable on the server, linked to the MCP server.

Session-Level Tool Configuration

  • The user can enable/disable MCP servers for specific chat sessions.
  • The user can select which tools from each MCP server are enabled for the current chat session.
  • Default tool enablement for new sessions follows a clear hierarchy (Tool override → Server default → Disabled).

UI & User Experience

  • A UI is available to view and manage MCP servers (list, add, edit, delete, test, discover/refresh).
  • The UI displays the list of available tools from each MCP server and allows for per-session enablement.

LLM Integration & Tool Execution

  • The LLM can request to call tools exposed by local MCP servers.
  • Tool execution uses WebSocket for bidirectional communication between the server and the client.
  • The client executes MCP tools locally on behalf of the LLM and sends results back to the server.
  • The server receives tool results and forwards them to the LLM, supporting multi-turn tool calling.

Implementation Plan

The work is broken down into the following phases:

  • Phase 1: Foundation (US1.0 - US1.4)
    • US1.0: Encrypted Secret Storage Infrastructure (Client-Side)
    • US1.1: Local MCP Server ID Generation (Server-Side Minimal Storage)
    • US1.2: Local MCP Server DAO Layer (Server & Client)
    • US1.3: Local MCP Tool Definition Linkage
    • US1.4: Local MCP Server Service Layer (Server-Side)
  • Phase 2: Client Infrastructure (US2.1 - US2.4)
    • US2.1: Local MCP Server Process Manager
    • US2.2: Local MCP Server Manager (High-Level Orchestration)
    • US2.3: MCP Client Service (MCP Operations Layer)
    • US2.4: Local MCP Server Connection Testing UI
  • Phase 3: Tool Discovery (US3.1 - US3.2)
    • US3.1: Local MCP Tool Discovery and Persistence
    • US3.2: Tool Refresh Mechanism
  • Phase 4: Tool Execution (US4.1 - US4.3)
    • US4.1: Local MCP Tool Executor
    • US4.2: WebSocket Message Processing Integration
    • US4.3: Client-Side Local MCP Tool Execution Handler
  • Phase 5: API & Routes (US5.1 - US5.2)
    • US5.1: Local MCP Server API Routes (ID Generation)
    • US5.2: Local MCP Tool Management API Routes
  • Phase 6: Frontend Integration (US6.1 - US6.5)
    • US6.1: Local MCP Server Repository (Client-Side Local Storage)
    • US6.1A: Extend Tool Repository for MCP Tools
    • US6.2: Tool API Client Extensions
    • US6.3: Local MCP Server API Client
    • US6.4: Local MCP Server Management UI
    • US6.5: Local MCP Server Configuration Dialog
  • Phase 7: Session Integration (US7.1 - US7.2)
    • US7.1: Local MCP Tool Session Configuration
    • US7.2: Local MCP Server Auto-Start
  • Phase 8: Advanced Features (US8.1 - US8.3)
    • US8.1: Local MCP Tool Default Enablement for New Sessions
    • US8.2: Local MCP Server Health Monitoring
    • US8.3: Local MCP Tool Execution Logs

Key Design Decisions & Architecture
  • Local-First Architecture: Focus on local (STDIO) MCP servers running on the user's machine.
  • Client-Side Storage for MCP Server Configurations: Full configurations are stored locally in a SQLDelight database on each client platform (Desktop, Android, WASM). The server only stores a minimal record (id, userId) for linkage.
  • Tool Name Uniqueness: Tool names are not globally unique. Uniqueness is only required within the set of enabled tools for a given chat session.
  • Security & Privacy: Environment variables containing secrets are encrypted client-side using a reusable EncryptedSecretTable.
  • Two-Level Default Enablement: New chat sessions can have tools enabled by default based on a server-level setting (LocalMCPServer.toolsEnabledByDefault) with a tool-level override (ToolDefinition.isEnabledByDefault).
  • Client-Side Operations: Tool discovery, refresh, and connection testing are client-side operations that do not require dedicated server API endpoints.
  • WebSocket Integration: The POST /api/v1/sessions/{sessionId}/messages route will be upgraded to use WebSockets to enable the bidirectional communication required for tool execution.

Component Responsibilities

  • Server-Side: Generates unique IDs for MCP servers, stores tool definitions, and orchestrates tool execution requests via WebSocket.
  • Client-Side:
    • LocalMCPServerRepository: Manages local storage of MCP server configurations.
    • ToolRepository (Extended): Manages persistence of all tools, including those from MCP servers.
    • LocalMCPServerManager: A high-level orchestration service that coordinates workflows like tool discovery and connection testing.
    • MCPClientService: A lower-level service that handles direct interaction with the MCP SDK and manages server processes.
    • LocalMCPServerProcessManager: Manages the lifecycle of local MCP server OS processes.
## Description As a user, I want the LLM to be able to call local tools via the Model Context Protocol (MCP), so that the LLM can access real-time data and perform actions in the external world (such as searching the web, accessing local files, controlling GitHub repos, etc.). This epic covers the end-to-end implementation for configuring, managing, and executing tools from local MCP servers running on a user's machine. --- ## Acceptance Criteria ### MCP Server Configuration - [ ] The user can configure their own local (STDIO) MCP servers with a name, command, arguments, and environment variables. - [ ] Environment variables are encrypted client-side for security. - [ ] The user can configure auto-start (`autoStartOnEnable`, `autoStartOnLaunch`) and auto-stop (`autoStopAfterInactivitySeconds`) behavior. - [ ] The user can set default tool enablement for new sessions (`toolsEnabledByDefault`). ### MCP Server Management - [ ] The user can test the connection to an MCP server. - [ ] The user can discover tools from an MCP server, which persists them to the database. - [ ] The user can refresh the list of tools from an MCP server (adding new, updating changed, removing deleted). - [ ] MCP servers can be started and stopped from within the application, with their status tracked. ### Data Persistence - [ ] MCP server configurations are stored locally on the client machine using SQLDelight. - [ ] The server stores a minimal record (`id`, `userId`) for linkage purposes. - [ ] MCP tools are stored in the central `ToolDefinitionTable` on the server, linked to the MCP server. ### Session-Level Tool Configuration - [ ] The user can enable/disable MCP servers for specific chat sessions. - [ ] The user can select which tools from each MCP server are enabled for the current chat session. - [ ] Default tool enablement for new sessions follows a clear hierarchy (Tool override → Server default → Disabled). ### UI & User Experience - [ ] A UI is available to view and manage MCP servers (list, add, edit, delete, test, discover/refresh). - [ ] The UI displays the list of available tools from each MCP server and allows for per-session enablement. ### LLM Integration & Tool Execution - [ ] The LLM can request to call tools exposed by local MCP servers. - [ ] Tool execution uses WebSocket for bidirectional communication between the server and the client. - [ ] The client executes MCP tools locally on behalf of the LLM and sends results back to the server. - [ ] The server receives tool results and forwards them to the LLM, supporting multi-turn tool calling. --- ## Implementation Plan The work is broken down into the following phases: - **Phase 1: Foundation (US1.0 - US1.4)** - [ ] **US1.0**: Encrypted Secret Storage Infrastructure (Client-Side) - [ ] **US1.1**: Local MCP Server ID Generation (Server-Side Minimal Storage) - [ ] **US1.2**: Local MCP Server DAO Layer (Server & Client) - [ ] **US1.3**: Local MCP Tool Definition Linkage - [ ] **US1.4**: Local MCP Server Service Layer (Server-Side) - **Phase 2: Client Infrastructure (US2.1 - US2.4)** - [ ] **US2.1**: Local MCP Server Process Manager - [ ] **US2.2**: Local MCP Server Manager (High-Level Orchestration) - [ ] **US2.3**: MCP Client Service (MCP Operations Layer) - [ ] **US2.4**: Local MCP Server Connection Testing UI - **Phase 3: Tool Discovery (US3.1 - US3.2)** - [ ] **US3.1**: Local MCP Tool Discovery and Persistence - [ ] **US3.2**: Tool Refresh Mechanism - **Phase 4: Tool Execution (US4.1 - US4.3)** - [ ] **US4.1**: Local MCP Tool Executor - [ ] **US4.2**: WebSocket Message Processing Integration - [ ] **US4.3**: Client-Side Local MCP Tool Execution Handler - **Phase 5: API & Routes (US5.1 - US5.2)** - [ ] **US5.1**: Local MCP Server API Routes (ID Generation) - [ ] **US5.2**: Local MCP Tool Management API Routes - **Phase 6: Frontend Integration (US6.1 - US6.5)** - [ ] **US6.1**: Local MCP Server Repository (Client-Side Local Storage) - [ ] **US6.1A**: Extend Tool Repository for MCP Tools - [ ] **US6.2**: Tool API Client Extensions - [ ] **US6.3**: Local MCP Server API Client - [ ] **US6.4**: Local MCP Server Management UI - [ ] **US6.5**: Local MCP Server Configuration Dialog - **Phase 7: Session Integration (US7.1 - US7.2)** - [ ] **US7.1**: Local MCP Tool Session Configuration - [ ] **US7.2**: Local MCP Server Auto-Start - **Phase 8: Advanced Features (US8.1 - US8.3)** - [ ] **US8.1**: Local MCP Tool Default Enablement for New Sessions - [ ] **US8.2**: Local MCP Server Health Monitoring - [ ] **US8.3**: Local MCP Tool Execution Logs --- <details> <summary><h3>Key Design Decisions & Architecture</h3></summary> - **Local-First Architecture**: Focus on local (STDIO) MCP servers running on the user's machine. - **Client-Side Storage for MCP Server Configurations**: Full configurations are stored locally in a SQLDelight database on each client platform (Desktop, Android, WASM). The server only stores a minimal record (`id`, `userId`) for linkage. - **Tool Name Uniqueness**: Tool names are **not** globally unique. Uniqueness is only required within the set of enabled tools for a given chat session. - **Security & Privacy**: Environment variables containing secrets are encrypted client-side using a reusable `EncryptedSecretTable`. - **Two-Level Default Enablement**: New chat sessions can have tools enabled by default based on a server-level setting (`LocalMCPServer.toolsEnabledByDefault`) with a tool-level override (`ToolDefinition.isEnabledByDefault`). - **Client-Side Operations**: Tool discovery, refresh, and connection testing are client-side operations that do not require dedicated server API endpoints. - **WebSocket Integration**: The `POST /api/v1/sessions/{sessionId}/messages` route will be upgraded to use WebSockets to enable the bidirectional communication required for tool execution. #### Component Responsibilities - **Server-Side**: Generates unique IDs for MCP servers, stores tool definitions, and orchestrates tool execution requests via WebSocket. - **Client-Side**: - **`LocalMCPServerRepository`**: Manages local storage of MCP server configurations. - **`ToolRepository` (Extended)**: Manages persistence of all tools, including those from MCP servers. - **`LocalMCPServerManager`**: A high-level orchestration service that coordinates workflows like tool discovery and connection testing. - **`MCPClientService`**: A lower-level service that handles direct interaction with the MCP SDK and manages server processes. - **`LocalMCPServerProcessManager`**: Manages the lifecycle of local MCP server OS processes. </details>
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
test/credential-validator-fixture-umask
feat/credential-profile-agent-roles
fix/credential-secret-tree-removal
feat/terminal-session-credential-attach
feat/worker-terminal-session
feat/worker-command-uid-isolation
v0.11.0
v0.10.0
v0.9.0
v0.8.0
v0.7.0
v0.6.0
v0.5.1
v0.5.0
v0.4.0
v0.3.0
v0.2.0
v0.1.0
Labels
Clear labels   
Epic 5

   
MCP

   
P1

   
PR-0

   
PR-1

   
api

   
api-layer

   
architecture

   
area:backend

   
area:frontend

   
arrow

   
authentication

   
backend

   
bug
Something isn't working

  
chat

   
client

   
clipboard

   
common-module

   
compose

   
cross-cutting

   
cross-cutting-requirement

   
data-layer

   
data-models

   
database

   
desktop-client

   
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
epic

   
epic-1

   
epic-2

   
epic-3

   
epic-4

   
epic-5

   
epic-6

   
epic-7

   
epic-llm-config

   
error-handling

   
feature

   
frontend

   
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
implementation

   
infrastructure

   
installer

   
invalid
This doesn't seem right

  
kotlin

   
ktor

   
llm

   
medium-priority

   
message

   
multiplatform

   
needs-review

   
needs-triage

   
packaging

   
performance

   
phase-1

   
phase-2

   
phase-3

   
phase-4

   
phase-5

   
phase3

   
phase:3

   
priority: high

   
question
Further information is requested

  
refactor

   
refactoring

   
resource-sharing

   
security

   
server

   
server-module

   
services

   
session

   
session-management

   
settings

   
setup

   
shutdown

   
state

   
storage

   
streaming

   
sub-issue

   
tests

   
tooling

   
type:task

   
ui

   
ui/ux

   
user-accounts

   
user-management

   
ux

   
viewmodel

   
websocket

   
windows

   
windows-integration

   
wontfix
This will not be worked on

No labels
Epic 5
MCP
P1
PR-0
PR-1
api
api-layer
architecture
area:backend
area:frontend
arrow
authentication
backend
bug
chat
client
clipboard
common-module
compose
cross-cutting
cross-cutting-requirement
data-layer
data-models
database
desktop-client
documentation
duplicate
enhancement
epic
epic-1
epic-2
epic-3
epic-4
epic-5
epic-6
epic-7
epic-llm-config
error-handling
feature
frontend
good first issue
help wanted
implementation
infrastructure
installer
invalid
kotlin
ktor
llm
medium-priority
message
multiplatform
needs-review
needs-triage
packaging
performance
phase-1
phase-2
phase-3
phase-4
phase-5
phase3
phase:3
priority: high
question
refactor
refactoring
resource-sharing
security
server
server-module
services
session
session-management
settings
setup
shutdown
state
storage
streaming
sub-issue
tests
tooling
type:task
ui
ui/ux
user-accounts
user-management
ux
viewmodel
websocket
windows
windows-integration
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
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
Torvian.eu/chatbot#121
No description provided.