# 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
```bash
npm install
```
2) Configure env
Create a `.env` in project root:
```
CODE=YOUR_SPLID_INVITE_CODE
PORT=8000
```
3) Build and run
```bash
npm run build
npm run dev
```
4) Inspect locally
```bash
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):
```json
{
"title": "Dinner",
"amount": 12.5,
"payers": [{ "name": "Alice", "amount": 12.5 }],
"profiteers": [{ "name": "Bob", "share": 0.6 }, { "name": "Alice", "share": 0.4 }]
}
```
- Example (userIds):
```json
{
"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