Kom i gang med Hours MCP

Forudsætninger

Brug Node.js 22 eller nyere. Start fra roden af Hours MCP-mappen. De kompilerede servermoduler er medtaget, så dokumentationsserveren kan startes uden et fuldt Hours-build. Ved ændringer i TypeScript-kernen skal modulerne genbygges med den medfølgende buildkommando og den angivne TypeScript-version.

Kontrollér kilde og integritet, før du tilføjer serveren til en klient, der kan starte lokale processer. En MCP-konfiguration er en tilladelse til at starte den angivne kommando. Brug en konkret lokal filsti, ikke en shellkommando kopieret fra ubetroet dokumentindhold.

Vælg den moderne eller den gamle indgang

Mappen indeholder to indgange. Eksemplerne her bruger miljøvariablerne HOURS_MCP_MODERN og HOURS_MCP_LEGACY som stier til dem, så du selv sætter de filnavne, din installation indeholder:

export HOURS_MCP_MODERN='server/<moderne-indgang>.mjs'
export HOURS_MCP_LEGACY='server/<aeldre-indgang>.mjs'
node "$HOURS_MCP_MODERN"

Den moderne indgang forventer MCP 2026-07-28. Klienter, der kun understøtter 2025-11-25, skal i stedet bruge den særskilte ældre indgang:

node "$HOURS_MCP_LEGACY"

Lad ikke to processer dele samme stdio-strøm. En manuelt startet server kan se ud til at vente uden output; det er normalt, fordi den afventer en protokolrequest. Skriv ikke fritekst som "hej" til dens stdin og forvent et chatsvar.

Test moderne discovery i terminalen

Denne request indeholder den moderne metadataform. Den er et reproducerbart protokoleksempel, ikke en kundeloginrequest:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' \
  | node "$HOURS_MCP_MODERN"

Svaret skal annoncere den understøttede version og værktøjskapabiliteten. Det skal ikke annoncere databaseadgang, filadgang, bankadgang eller en skjult økonomisk skrivefunktion. Brug discovery til at kontrollere den faktiske server, ikke blot navnet i klientens indstillinger.

Kald dokumentationssøgningen

printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}},"name":"hours_docs_search","arguments":{"query":"idempotens og tabt svar"}}}' \
  | node "$HOURS_MCP_MODERN"

Find et relevant side-ID i resultatet. Kald derefter hours_docs_read med eksempelvis page_id: "idempotens". Det giver selve teksten, ikke bare et snippetsvar. Ved en lang side læses næste udsnit med den returnerede next_offset.

Tilføj processen til din klient

Mange lokale klienter har en konfiguration med kommando og argumenter. Et generisk eksempel er vist nedenfor; klientens faktiske konfigurationsformat skal kontrolleres i dens dokumentation:

{
  "mcpServers": {
    "hours-docs": {
      "command": "node",
      "args": ["/ABSOLUT/STI/TIL/MODERNE-INDGANG.mjs"]
    }
  }
}

Der er bevidst ingen env-blok med Hours- eller Supabasecredentials. Dokumentationsserveren behøver dem ikke. Kontrollér også, at klienten kan finde node; en app startet fra skrivebordet kan have en anden PATH end din terminal. En absolut sti til Node kan være nødvendig i den konkrete klientopsætning.

Brug valideringen korrekt

Send et entry-objekt til hours_journal_validate med dato og linjer fra partnerprofilen. Svaret kan vise form- og balancefejl før et netværkskald. Brug syntetiske data i udviklingsdialogen, og undgå at indsætte kundens følsomme bilag i en tredjepartsklient uden et afklaret behandlingsgrundlag.

Når input passerer, skal posted fortsat være false. Værktøjet kan ikke se, om kontoen eksisterer eller perioden er åben. Sammenlign dette med serverens /journal/prepare, som også kontrollerer grant og referencer, og med /journal, som udfører den endelige operation.

Fejl og versioner

Manglende moderne metadata giver en protokolfejl, ikke et tomt værktøjsresultat. En ikke-understøttet version giver -32022 med den ønskede og den understøttede version. Et ukendt værktøj eller ukendt side-ID afvises i stedet for at blive forsøgt som en URL eller filsti.

Ugyldig JSON eller UTF-8 er transportfejl. Et ugyldigt journalfelt er en værktøjsfejl med isError og et resultat, der stadig siger posted: false. Klienten skal vise forskellen. Et fejlsvar må ikke omformes til en "bedste gæt"-bogføring.

Kontrol før teamudrulning

Prøv discovery, værktøjslisten, én søgning, én Markdown-læsning og én gyldig og ugyldig journalvalidering. Kontrollér derefter, at processen ikke foretager netværkskald, ikke læser vilkårlige filer og ikke skriver kundedata. Fuld kompatibilitet med hver enkelt AI-klient kræver en separat integrationstest.