sprout-mcp

MCP server that provides a static, queryable reference library for the Sprout.ph API (HR, Payroll, Ecosystem Integration). Internal developers use it to look up endpoints, parameters, and auth requirements without leaving their AI assistant.

How it works

1. npm run fetch-docs pulls the full Postman collection JSON from the Sprout API docs site and writes structured JSON files per API section to src/data/
2. The MCP server reads those files at startup and registers one tool per section
3. list_library gives the agent a table of contents; domain tools (e.g. get_full_access_api_employee_service_ref) return the full endpoint reference for a section

No browser or Playwright required — the docs site is a Postman Documenter page that exposes its collection via a public JSON API.

Setup

1. Install dependencies

npm install

2. Configure environment

Create a .env file in the project root:

PORT=3456

3. Fetch the Sprout API docs

npm run fetch-docs

This populates src/data/ with one JSON file per API section plus an _index.json manifest. Re-run whenever Sprout updates their docs.

4. Start the MCP server

npm run dev       # development (tsx, no build step)
npm start         # production (requires npm run build first)

5. Connect your MCP client

Add to Claude Code settings or Claude Desktop config:

{
  "mcpServers": {
    "sprout-api": {
      "type": "http",
      "url": "http://localhost:3456/mcp"
    }
  }
}

Available tools

Tool	Description
list_library	Returns a table of contents of all available API sections
get_authorization_service_authorization_service_ref	Authorization Service — token endpoints
get_full_access_api_employee_service_ref	Full-Access API — Employee Service (52 endpoints)
get_full_access_api_hr_general_service_ref	Full-Access API — HR General Service (18 endpoints)
get_full_access_api_time_and_attendance_service_ref	Full-Access API — Time and Attendance Service (49 endpoints)
get_full_access_api_payroll_service_ref	Full-Access API — Payroll Service (20 endpoints)
get_restricted_access_api_employee_service_developer_gateway_ref	Restricted Access API — Employee Service (51 endpoints)
get_restricted_access_api_time_and_attendance_service_developer_gateway_ref	Restricted Access API — Time and Attendance Service (49 endpoints)
get_restricted_access_api_hr_general_service_developer_gateway_ref	Restricted Access API — HR General Service (17 endpoints)
get_restricted_access_api_payroll_service_developer_gateway_ref	Restricted Access API — Payroll Service (20 endpoints)

All API calls require the Ocp-Apim-Subscription-Key header with your assigned key.

Development

npm run dev          # run server via tsx (reads .env)
npm test             # run unit tests
npm run test:watch   # watch mode
npm run build        # compile TypeScript to dist/

Refreshing docs

When Sprout updates their API documentation:

npm run fetch-docs

The fetcher overwrites all files in src/data/ and regenerates _index.json. No code changes needed — new sections are picked up automatically on next server start.

Project structure

sprout-mcp/
├── scripts/
│   ├── fetch-docs.ts       # Postman collection JSON fetcher
│   └── diagnose.ts         # DOM diagnostic tool (debug helper)
├── src/
│   ├── server.ts           # MCP server entry point
│   ├── tools/
│   │   ├── types.ts        # Shared interfaces
│   │   ├── list-library.ts # list_library tool
│   │   └── registry.ts     # Dynamic tool registration + endpoint formatter
│   └── data/               # Generated by fetch-docs — not committed to git
│       ├── _index.json
│       └── *.json
└── tests/
    ├── list-library.test.ts
    └── registry.test.ts