# 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

```bash
npm install
```

### 2. Configure environment

Create a `.env` file in the project root:

```env
PORT=3456
```

### 3. Fetch the Sprout API docs

```bash
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

```bash
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:

```json
{
  "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

```bash
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:

```bash
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
```