Architecture

the litmus mcp server is two cooperating processes packaged in one container processes process file port role mcp server src/server py 8000 implements the mcp protocol over sse exposes 57 tools and a set of litmus\ //docs/ resources web client src/web client py 9000 fastapi app chat ui, config pages, llm streaming, multi instance management launches server py as a subprocess both ports come from a single docker image the web ui is optional; clients can hit the sse endpoint directly without ever touching port 9000 request flow (web ui) browser | \| post /chat v web client py > client utils process streaming query | \| anthropic messages stream() / openai / gemini v llm provider | \| tool use events v session call tool(name, args) | v mcp server (port 8000) | v server py handle call tool | v tools/\<category> tools py | v litmus edge rest / nats / influxdb request flow (external mcp client) claude desktop / cursor / vs code / windsurf / claude code | \| sse (with headers) v mcp server (port 8000) | v tools/\<category> tools py | v litmus edge rest / nats / influxdb authentication the server is stateless every tool call receives a request object and pulls credentials from headers (sse mode) or environment variables (stdio mode) at call time, via helpers in src/utils/auth py get litmus connection(request) litmus edge rest/sdk get nats connection params(request) nats broker get influx connection params(request) influxdb this means a single mcp server can be shared across many users, each presenting their own headers there is no server side session, no shared credentials multi instance edge support the web ui lets you register multiple litmus edge devices and switch between them internally, instances live in env as edge instance 1 url= edge instance 1 client id= edge instance 1 client secret= edge instance 1 name= edge instance 2 url= active edge instance=1 the active instance's credentials are mirrored into the canonical edge url , edge api client id , edge api client secret keys so the rest of the system needs no awareness of multi tenancy see multi instance edge # transport modes mode when to use auth source sse (default) remote or shared mcp server, any http capable client http headers per connection stdio single user local install with claude desktop environment variables stdio is opt in via enable stdio=true in src/config py or environment source layout src/ ├── server py mcp server entrypoint, sse setup ├── web client py fastapi app, all web routes ├── client utils py llm streaming, tool call loop ├── env config py env read/write, path constants ├── config py ports, ssl, nats/influxdb defaults ├── conversation py in memory chat history ├── utils/ │ ├── auth py header > connection params │ └── formatting py tool response shape helpers └── tools/ ├── devicehub tools py ├── dm tools py ├── marketplace tools py ├── data tools py ├── digitaltwins tools py ├── system tools py ├── lem tools py └── resource tools py mcp resources (live docs litmus io) each tools py exports a tools = \[ ] list of dicts server py concatenates them and dispatches by name