Splid MCP Server

A Model Context Protocol (MCP) server that exposes Splid (splid.app) via tools, powered by the reverse‑engineered splid-js client.

• Language/Runtime: Node.js (ESM) + TypeScript
• Transport: Streamable HTTP (and stdio for local inspector)
• License: MIT

Quick start

1. Install

npm install

2. Configure env

Create a .env in project root:

CODE=YOUR_SPLID_INVITE_CODE
PORT=8000

3. Build and run

npm run build
npm run dev

4. Inspect locally

npm run inspect

Then connect to http://localhost:8000/mcp using "Streamable HTTP".

Tools

All tools support an optional group selector to override the default from CODE:

• groupId?: string
• groupCode?: string (invite code)
• groupName?: string (reserved; not yet supported)

If none provided, the server uses the default group from CODE.

health

• Purpose: connectivity check
• Output: { ok: true }

whoami

• Purpose: show the currently selected group and its members
• Input: none
• Output: JSON containing group info and members

createExpense

• Purpose: create a new expense entry
• Input:
  • title: string
  • amount: number > 0
  • currencyCode?: string (defaults to the group default when omitted)
  • payers: { userId?: string; name?: string; amount: number > 0 }[] (at least 1)
  • profiteers: { userId?: string; name?: string; share: number in (0,1] }[] (at least 1)
  • Optional group selector fields
• Rules:
  • Names are case‑insensitive and resolved to member GlobalId; unknown names return a clear error.
  • The sum of all share values must equal 1 (±1e‑6).
• Example (names):

{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "name": "Alice", "amount": 12.5 }],
  "profiteers": [{ "name": "Bob", "share": 0.6 }, { "name": "Alice", "share": 0.4 }]
}

• Example (userIds):

{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "userId": "<GlobalId>", "amount": 12.5 }],
  "profiteers": [{ "userId": "<GlobalId>", "share": 1 }]
}

listEntries

• Purpose: list recent entries in a group
• Input:
  • limit?: number (1..100, default 20)
  • Optional group selector fields
• Output: array of entries

getGroupSummary

• Purpose: show balances/summary for a group
• Input:
  • Optional group selector fields
• Output: summary object (balances computed via Splid)

Streamable HTTP

• URL: http://localhost:8000/mcp
• No auth headers required; use MCP Inspector to test.

Troubleshooting

• "Bad Request: Server not initialized": refresh and reconnect; first POST must be initialize.
• 400 with share errors: ensure shares are in (0,1] and sum to 1.
• Unknown name: check exact member names in whoami output.

Configuration

• Env variables:
  • CODE: Splid invite/join code for the default group
  • PORT (optional): default 8000

Acknowledgements

• Splid JS client: https://github.com/LinusBolls/splid-js
• MCP Server template / docs: https://github.com/InteractionCo/mcp-server-template

License

MIT