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. A one-time Playwright scraper (npm run fetch-docs) crawls https://api-docs.sprout.ph/ 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_hr_employees_ref) return the full endpoint reference for a section

Related MCP server: devdocs-mcp

Setup

1. Install dependencies

npm install

2. Install Playwright browser

npx playwright install chromium

3. Scrape the Sprout API docs

npm run fetch-docs

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

4. Start the MCP server

npm start

The server listens on port 3000 by default. Set PORT to override:

PORT=4000 npm start

5. Connect your Claude client

Add to your Claude Code settings (.claude/settings.json) or Claude Desktop config (claude_desktop_config.json):

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

Available tools

Example usage in Claude

You: How do I get a list of employees from Sprout?

Claude: [calls list_library → sees get_hr_employees_ref → calls it]
       GET https://api.sprout.ph/v2/hr/employees
       Auth: Authorization: Bearer {token} | Ocp-Apim-Subscription-Key: {key}
       ...

Development

npm run dev          # run server with hot-reload via tsx
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
npm start

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

Project structure

sprout-mcp/
├── scripts/
│   └── fetch-docs.ts       # Playwright scraper (run with npm run fetch-docs)
├── src/
│   ├── server.ts           # MCP server entry point
│   ├── tools/
│   │   ├── types.ts        # Shared types
│   │   ├── list-library.ts # list_library tool
│   │   └── registry.ts     # Dynamic tool registration + endpoint formatter
│   └── data/               # Generated by scraper — not committed to git
│       ├── _index.json
│       ├── hr_employees.json
│       └── ...
└── tests/
    ├── list-library.test.ts
    └── registry.test.ts