Splid MCP

Um servidor Model Context Protocol (MCP) que expõe o Splid (splid.app) por meio de ferramentas, alimentado pelo cliente splid-js com engenharia reversa.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor Splid MCP

Um servidor Model Context Protocol (MCP) que expõe o Splid (splid.app) por meio de ferramentas, alimentado pelo cliente de engenharia reversa splid-js.

  • Linguagem/Runtime: Node.js (ESM) + TypeScript
  • Transporte: Streamable HTTP (e stdio para inspetor local)
  • Licença: MIT

Início rápido

  1. Instalação
npm install
  1. Configure o ambiente

Crie um .env na raiz do projeto:

CODE=YOUR_SPLID_INVITE_CODE
PORT=8000
  1. Compile e execute
npm run build
npm run dev
  1. Inspecione localmente
npm run inspect

Em seguida, conecte-se a http://localhost:8000/mcp usando "Streamable HTTP".

Ferramentas

Todas as ferramentas suportam um seletor de grupo opcional para substituir o padrão de CODE:

  • groupId?: string
  • groupCode?: string (código de convite)
  • groupName?: string (reservado; ainda não suportado)

Se nenhum for fornecido, o servidor usa o grupo padrão de CODE.

health

  • Objetivo: verificação de conectividade
  • Saída: { ok: true }

whoami

  • Objetivo: mostrar o grupo atualmente selecionado e seus membros
  • Entrada: nenhuma
  • Saída: JSON contendo informações do grupo e membros

createExpense

  • Objetivo: criar uma nova entrada de despesa

  • Entrada:

    • title: string
    • amount: number > 0
    • currencyCode?: string (padrão é o padrão do grupo quando omitido)
    • payers: { userId?: string; name?: string; amount: number > 0 }[] (pelo menos 1)
    • profiteers: { userId?: string; name?: string; share: number in (0,1] }[] (pelo menos 1)
    • Campos opcionais do seletor de grupo

  • Regras:

    • Nomes são insensíveis a maiúsculas/minúsculas e resolvidos para o GlobalId do membro; nomes desconhecidos retornam um erro claro.
    • A soma de todos os valores de share deve ser igual a 1 (±1e‑6).

  • Exemplo (nomes):

{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "name": "Alice", "amount": 12.5 }],
  "profiteers": [{ "name": "Bob", "share": 0.6 }, { "name": "Alice", "share": 0.4 }]
}
  • Exemplo (userIds):
{
  "title": "Dinner",
  "amount": 12.5,
  "payers": [{ "userId": "<GlobalId>", "amount": 12.5 }],
  "profiteers": [{ "userId": "<GlobalId>", "share": 1 }]
}

listEntries

  • Objetivo: listar entradas recentes em um grupo
  • Entrada:
    • limit?: number (1..100, padrão 20)
    • Campos opcionais do seletor de grupo
  • Saída: array de entradas

getGroupSummary

  • Objetivo: mostrar saldos/resumo de um grupo
  • Entrada:
    • Campos opcionais do seletor de grupo
  • Saída: objeto de resumo (saldos calculados via Splid)

Streamable HTTP

  • URL: http://localhost:8000/mcp
  • Nenhum cabeçalho de autenticação necessário; use o MCP Inspector para testar.

Solução de problemas

  • "Bad Request: Server not initialized": atualize e reconecte; o primeiro POST deve ser initialize.
  • 400 com erros de partilha: garanta que as partilhas estejam em (0,1] e somem 1.
  • Nome desconhecido: verifique os nomes exatos dos membros na saída de whoami.

Configuração

  • Variáveis de ambiente:
    • CODE: código de convite/entrada do Splid para o grupo padrão
    • PORT (opcional): padrão 8000

Agradecimentos

Licença

MIT