# Sage Intacct Documentation MCP Server

An MCP server that gives AI assistants queryable access to Sage Intacct REST API documentation. Load one or more OpenAPI specs and let your LLM search endpoints, browse schemas, generate example payloads, and check documentation quality — all without leaving the conversation.

## Quick Start

**1. Install**

```bash
npm install -g @rowellewis/intacct-docs-mcp
```

Or run without installing:

```bash
npx @rowellewis/intacct-docs-mcp
```

**2. Add to Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "intacct-docs": {
      "command": "npx",
      "args": ["-y", "@rowellewis/intacct-docs-mcp"],
      "env": {
        "SPEC_DIR": "/path/to/your/specs"
      }
    }
  }
}
```

Omit `SPEC_DIR` to use the bundled Sage Intacct spec.

**3. Try it**

> "Search for endpoints related to accounts payable vendors."
> "Show me the request body schema for POST /objects/accounts-payable/vendor."
> "Generate an example payload for creating a journal entry."

## Tools

| Tool | What it does |
|------|-------------|
| `search-endpoints` | Fuzzy full-text search across paths, summaries, and descriptions. Supports multi-word queries and typo tolerance. |
| `get-endpoint-docs` | Full documentation for a specific endpoint — parameters, request/response schemas, examples. |
| `get-schema` | Schema definition with all properties, types, and constraints. |
| `list-schemas` | Browse available schema names, filterable by prefix. |
| `list-tags` | All API tags/categories with endpoint counts. |
| `get-endpoints-by-tag` | All endpoints under a specific tag. Use `list-tags` first to find tag names. |
| `generate-example` | Generates a realistic JSON request body for any endpoint, inferred from its schema. |
| `spec-quality-report` | Scores documentation quality (0–100) and lists issues by severity. |
| `health` | Readiness status, index counts, and startup timing. |

Full parameter reference, error codes, and examples: [`docs/public-contract.md`](docs/public-contract.md).

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `SPEC_DIR` | `../data/sage-intacct-rest-api` | Directory scanned for `*.openapi.yaml` files |
| `TRANSPORT` | `stdio` | `stdio` or `http` |
| `HTTP_PORT` | `3000` | Port when using HTTP transport |
| `HTTP_HOST` | `127.0.0.1` | Bind address for HTTP transport (`0.0.0.0` for all interfaces) |
| `MAX_RESPONSE_CHARS` | `12000` | Response size cap — output is truncated with a notice when exceeded |
| `LOG_LEVEL` | `info` | `error`, `warn`, `info`, or `debug` |
| `MAX_BODY_BYTES` | `1048576` | Maximum HTTP request body size in bytes |
| `RATE_LIMIT_RPM` | `60` | Max requests per minute per IP (HTTP transport) |

## Development

```bash
npm install
npm run build   # compile TypeScript
npm run dev     # watch mode with tsx
npm test        # run all tests
```

Node.js >=18 required.

**Project layout:**

```
src/
├── app.ts                  # tool registry and handlers
├── config.ts               # env vars → AppConfig
├── index.ts                # entry point, transport selection
├── core/
│   ├── indexer.ts          # in-memory indexes + fuzzy search
│   ├── formatter.ts        # markdown response formatting
│   ├── fuzzy.ts            # trigram similarity matching
│   ├── example-generator.ts
│   ├── validate.ts
│   ├── cache.ts
│   └── spec-quality.ts
└── transport/
    ├── http-server.ts      # MCP Streamable HTTP transport + GET /health
    └── stdio.ts            # MCP stdio wrapper
```

Tests use Vitest.

## Deployment

**HTTP transport** (MCP Streamable HTTP — for URL-based MCP clients):

```bash
TRANSPORT=http HTTP_PORT=3000 npm start
```

## Operations

- **Health:** call the `health` tool — returns readiness, index counts, and startup duration. Or hit `GET /health` when running in HTTP mode.
- **Logs:** structured JSON on stderr. Adjust verbosity with `LOG_LEVEL`.
- **Runbook:** [`docs/ops-runbook.md`](docs/ops-runbook.md)

## Troubleshooting

**Server won't start** — verify `SPEC_DIR` contains at least one `*.openapi.yaml` file, then run `npm run build` and check stderr.

**Endpoint not found** — use `search-endpoints` to discover paths. Methods must be uppercase (`GET`, `POST`, …).

**Schema not found** — use `list-schemas` with an optional `prefix` to browse what's available. Names are case-sensitive.

## License

MIT