ioffice-mcp: Instructions file for Claude Code

ioffice-mcp

MCP server exposing iOffice workspace/facility management APIs to Claude. Uses stdio transport.

Commands

npm run build            # tsc + esbuild bundle → dist/index.js + dist/bundle.js
npm test                 # Run tests (vitest)
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report (100% thresholds enforced)
npm run dev              # node --env-file=.env dist/index.js (requires built dist)

Run locally (requires built dist):

IOFFICE_HOST=tenant.ioffice.com IOFFICE_TOKEN=xxx node dist/index.js

Tool naming

All tools are prefixed io_ (e.g. io_list_buildings, io_create_reservation, io_checkin_visitor).

Architecture

src/
  index.ts          # MCP server entry — runMcp() from @chrischall/mcp-utils, registers all tool modules, stdio transport
  client.ts         # IOfficeClient (thin wrapper over createApiClient from @chrischall/mcp-utils) + re-exported buildQueryString/buildOptionalBody + local optionalBody helper
  tools/
    buildings.ts    # io_{list,get,create,update,delete}_building
    floors.ts       # io_{list,get,create,update,delete}_floor
    spaces.ts       # io_{list,get,create,update,delete}_space
    users.ts        # io_{list,get,create,update,delete}_user
    reservations.ts # io_{list,get,create,update,delete,checkin,checkout}_reservation
    visitors.ts     # io_{list,get,create,update,checkin,checkout}_visitor
    maintenance.ts  # io_{list,get,create,update,accept,start,complete,archive}_maintenance_request
    mail.ts         # io_{list,get,create,deliver,return}_mail
    moves.ts        # io_{list,get,create,update,approve,cancel}_move

Each tool module exports a register<Domain>Tools(server, client) function that calls server.registerTool(...) with a zod input schema and a handler. index.ts constructs one IOfficeClient and hands it to runMcp({ deps: client, tools: [...] }), which passes it to every register call. Add new domains by mirroring this pattern (and add them to the tools array in index.ts).