Files
Evgeny @ SimpleX Chat b475ae25ac mcp: free memory and disk in the end line of answers (#8211)
* mcp: free memory and disk in the status line

* mcp: free memory and disk in the end line of answers

* mcp: ❗️ after a low part of the end line, RAM below 5%
2026-11-14 23:17:25 +00:00
..

SimpleX MCP server: specification

Technical specification of @simplex-chat/mcp 0.3.0 in packages/simplex-chat-mcp. It covers simplex-mcp serve and the Claude Code plugin. Statements are checked against the source of the same commit, and each section links to the code.

Related: README (the plugin's installation and use) | REFERENCE (serve and register, shared settings, options, commands, files, recovery) | PLAN (design record of serve) | plugin plan (decisions of the plugin) | TESTING (local build and test) | ROADMAP (what comes next)

Table of contents

  1. Executive summary
  2. Dependency graph
  3. Specification documents
  4. Source entry points
  5. Code references

Executive summary

@simplex-chat/mcp is a local server that gives an MCP host one SimpleX profile per process. The host reaches it with Streamable HTTP on 127.0.0.1 and a bearer token. The server exposes six tools: connect, send, receive, download, list and leave.

The SimpleX core (libsimplex, release core-7.1.3.0) runs inside the same Node.js process, loaded by the simplex-chat library 7.1.3. The core keeps the profile, chats and connections in two SQLite databases of the data folder, and sends and receives files through XFTP servers. The MCP protocol is served by the MCP TypeScript SDK (@modelcontextprotocol/server 2.3.1 and @modelcontextprotocol/node 2.1.1).

connect, send, download and leave are actions. In mode requests the server posts each action as a card in the agent control chat, a SimpleX group created and owned by the agent's profile. An owner approves or rejects the card with a command in that chat, and the server performs the action after the approval. An owner can also approve all messages to one chat, or all downloads of files on known servers from one chat, in advance. On a download card, the owner lets the agent receive the file, or has it forwarded only to the owner. In mode host the server performs actions at once and marks the four tools for the host's own confirmation.

A tool call is held open by the server until the owner decides and, for connect and send, until the replies arrive, and for download, until the file is received or wait passes. A repeated call with the same arguments is attached to the same action, so a call that the host ends early is resumed.

The server keeps actions and downloads in memory, and they are lost when the process exits. The action counter and the standing approvals are stored as custom data in the chat database. The token, the headers file for the host, the server record and the lock are files in the data folder; downloaded files are in its files folder, one folder per chat.

The package is also a Claude Code plugin. Each Claude Code session runs simplex-mcp session, a stdio MCP server. The session server forwards tool calls over a local socket to simplex-mcp service, one service per data root. Requests on the socket are HTTP/1.1 with a bearer token. The service runs two cores:

  • Claude is the profile that peers see. It holds the Main group, one group per session and the chats with peers. In a session's group it posts Claude's texts and answers, one line for each step, for each of Claude Code's own prompts and for each summary of the session's context. The last message of each answer ends with the end line of its turn.
  • User is a member of every session group. It posts the prompts typed in the terminal.

Each session has the six tools and reply, and its group has its own Actions and Control. A chat belongs to the session that connected it. Admins and owners of the session group move a chat to another session with /give.

Every member of the Main group is trusted with all sessions. The Main group's owners are invited to each session group as owners. Another member of the Main group joins a session group as an admin with /join N there.

Rights in a session group follow the member's role there, however the member joined:

  • Admins and owners send prompts and the group's / commands, and approve actions.
  • Moderators, members and authors send prompts. Claude answers each of their / commands with one refusal.
  • Admins and owners make other members observers with /observer #G ID.

Claude posts a member's rights at each join and each role change. Claude posts the files of reply in a session group at once. The core sends them only while files and media are allowed in the group's preferences.

The session server is also a Claude Code channel. The plugin passes each message in the session group to the running session as a prompt, except the messages of User and one-line / texts. It passes a reaction with one of the apps' eight emoji, of a member whose role sends, other than User, as the emoji after the quote line of the reacted message. It replies This reaction is not supported. to any other reaction, once for each member and reacted message. Claude Code runs no command from such a prompt. The plugin posts Claude Code's permission prompts in the group as cards. An admin or owner can approve a tool for the rest of the session there, and a PreToolUse hook of the plugin then allows its uses, while Claude Code's own rules still apply. The plugin's hooks post the terminal prompts and Claude's text as Claude writes it in the group, and end each answer with the end line of its turn, with its usage. The hooks keep the model and the effort level in the group's short description, and post their switches. An optional status line command adds the plan's usage to the end line.


Dependency graph

Solid edges are runtime imports. Dotted edges are type-only imports, removed by the compiler. Node.js built-in modules are left out.

graph TD
  cli["cli.ts"] --> serve["serve.ts"]
  cli --> register["register.ts"]
  cli --> session["session.ts"]
  cli --> service["service.ts"]
  cli --> hook["hook.ts"]
  cli --> owner["owner.ts"]
  cli --> messages["messages.ts"]
  cli --> log["log.ts"]
  cli -.-> actions["actions.ts"]
  serve --> control["control.ts"]
  serve --> tools["tools.ts"]
  serve --> actions
  serve --> core["core.ts"]
  serve --> http["http.ts"]
  serve --> files["files.ts"]
  serve --> messages
  serve --> log
  serve --> version["version.ts"]
  session --> client["client.ts"]
  session --> config["config.ts"]
  session --> tools
  session --> socket["socket.ts"]
  session --> files
  session --> log
  session --> version
  session -.-> protocol["protocol.ts"]
  session -.-> messages
  service --> hub["hub.ts"]
  service --> config
  service --> socket
  service --> files
  service --> protocol
  service --> log
  service --> version
  service -.-> actions
  service -.-> tools
  service -.-> messages
  hub --> mainGroup["main-group.ts"]
  hub --> user["user.ts"]
  hub --> control
  hub --> tools
  hub --> actions
  hub --> core
  hub --> serve
  hub --> files
  hub --> messages
  hub --> log
  hub --> config
  hub -.-> protocol
  mainGroup --> control
  mainGroup --> tools
  mainGroup --> log
  user --> core
  user --> tools
  user --> log
  hook --> client
  hook --> config
  hook --> qr["qr.ts"]
  hook --> socket
  hook --> files
  hook --> log
  hook --> version
  hook --> messages
  hook --> serviceRequest["service-request.ts"]
  hook -.-> protocol
  display["display.ts"] --> paths["paths.ts"]
  display --> serviceRequest
  statusLine["status-line.ts"] --> paths
  statusLine --> serviceRequest
  hub --> statusLine
  serviceRequest --> paths
  files --> paths
  owner --> client
  owner --> qr
  owner --> files
  owner --> version
  owner -.-> protocol
  client --> socket
  client --> files
  client --> protocol
  client --> log
  core --> files
  core --> log
  control --> tools
  control --> actions
  control --> messages
  control --> qr
  control --> log
  control -.-> serve
  tools --> actions
  tools --> messages
  tools --> log
  actions --> messages
  actions --> log
  actions -.-> tools
  config --> messages
  config -.-> actions
  protocol -.-> config
  protocol -.-> tools
  register --> files
  register --> log
  files --> log
  files -.-> actions
  http --> log
  socket --> log
  messages --> log
  serve --> sc["simplex-chat"]
  tools --> sc
  control --> sc
  core --> sc
  hub --> sc
  mainGroup --> sc
  user --> sc
  messages -.-> sc
  log --> sc
  tools --> mcps["@modelcontextprotocol/server"]
  serve --> mcps
  session --> mcps
  http --> mcps
  http --> mcpn["@modelcontextprotocol/node"]
  qr --> qrcode["qrcode"]
  version --> pkg["package.json"]
Module Role
cli.ts simplex-mcp entry point: commands, options, exit codes
serve.ts serve: start sequence, event dispatch, stop sequence
http.ts serve: HTTP listener, token check, /mcp route, SDK handler
register.ts register command: Claude Code entry of a serve agent
tools.ts tool schemas, descriptions, handlers, connect plans, perform steps, downloads, files to send, chat owners
actions.ts action records, state machine, expiry timers, per-session limits, stop
control.ts agent control chat and session groups: link, owners, owner commands, cards, counter
messages.ts message items and their files, item watch, waits, unread paging, display names, durations
core.ts one SimpleX core: init, user, network config, temp folder, event buffer, profile update
files.ts data folders, lock, token, headers.json, server.json, session folders, socket path, service log
log.ts log lines, error texts, shell quoting
qr.ts QR code text: small and large for terminals, plain for the hook message
version.ts package version from package.json
session.ts plugin: stdio MCP server of one Claude Code session, its channel, the forward of calls to the service
client.ts plugin: service client, version check, spawn
socket.ts plugin: HTTP over the local socket, token check, JSON and NDJSON
protocol.ts plugin: request and reply types of the socket routes, protocol version
service.ts plugin: routes, session registry, session IDs of one Claude Code process, attachments, idle close and stop, ready line
hub.ts plugin: the profile Claude, the sessions, their groups, prompts, opening messages, live texts, answers, end lines, steps and tool-use cards
main-group.ts plugin: the Main group, its owners, the list of sessions, /sessions, /join, owner reset
user.ts plugin: the profile User
hook.ts plugin: hook session-start and hook turn
display.ts plugin: the MessageDisplay hook, dist/display.js
status-line.ts plugin: the status line command, dist/status-line.js, and the plan's usage parts of the end line
service-request.ts plugin: one request to the running service within a time limit; CLAUDE_PID
paths.ts plugin: the data root, the socket path and the token file's name, with Node modules only
owner.ts plugin: link and reset-owners
config.ts plugin: option variables to Config, validation

Claude Code uses these files of the plugin, described in API 4.8:


Specification documents

Document Contents
Architecture system diagram, modules and types, state, process lifecycle, approval model, security boundaries, limits. Section 8 covers the plugin.
Flows sequence diagrams of the main flows with source locations. Flows 17-38 cover the plugin.
API the six tools, the control chat commands, replies and cards, the CLI. Section 4 covers the plugin's tools, groups, channel, socket protocol, commands and files.

Source entry points

Component File Key symbol
Binary simplex-mcp src/cli.ts main
Argument parser src/cli.ts parseCommand
Server start src/serve.ts startServer
Agent wiring and event dispatch src/serve.ts startAgent
HTTP listener src/http.ts startHttp
Tool registration src/tools.ts registerTools
Downloads src/tools.ts AgentTools.downloadFile
Action store src/actions.ts Actions
Agent control chat and session groups src/control.ts Control
Card text src/control.ts cardText
Item watch src/messages.ts ChatItemsWatch
Claude Code entry of serve src/register.ts register
Data folder files src/files.ts createDataFolder, acquireLock
Session server src/session.ts startSession
Session to service link src/session.ts ServiceLink
Service start by a client src/client.ts ServiceClient.ensureService
Service process src/service.ts runService
Service routes src/service.ts Service.routes
Hub src/hub.ts Hub.open
Session and its group src/hub.ts Session
Main group src/main-group.ts MainGroup
Profile User src/user.ts User
Hooks src/hook.ts sessionStart, turn
Display hook src/display.ts display
Status line command src/status-line.ts runStatusLine
link, reset-owners src/owner.ts showLink, resetOwners
SimpleX core src/core.ts openCore
Package manifest package.json bin.simplex-mcp

Code references

Functions, types and constants are named in the specs, and their files are linked without line numbers. A comment // spec: spec/FILE.md#ANCHOR is placed above each function, method, class, type or constant listed in a module table of Architecture or linked from an API section, where ANCHOR is the <a id> of a row or a section. Class fields, such as Session.turns, are given no comment. For a declaration whose output is specified field by field in an API section, such as a tool handler, a result object, a card, a command reply, a group profile or a socket route, the anchor of that section is given. For any other declaration, the anchor of its row is given, or, without a row, the anchor of the API section with a link to it. Line-number links in the package's documents, anchors defined twice, and // spec comments that differ from this form, point to a missing anchor or are not directly above a declaration are reported by the unit test spec.test.ts.