npm package: @halfords-pro/freeagent-mcp-invoice-search
Description: MCP server for searching invoices by reference number
Latest version: 2.0.3

# Invoice Search MCP Server

A Model Context Protocol (MCP) server that enables Claude to search for invoices by reference number.

## Features

- **Two search modes**:
  - Quick summary lookup: minimal data (~150 bytes)
  - Full invoice details: complete data including line items (~2-10KB)
- Health check and statistics tools
- Cloudflare Access authentication support
- Configurable API endpoint
- Simple JSON response format
- Built with TypeScript for type safety

## Prerequisites

- Node.js 18 or higher
- Access to an invoice API endpoint
- Cloudflare Access credentials (Client ID and Secret)

## Installation

1. Clone this repository:
```bash
git clone https://github.com/your-org/freeagent-mcp-invoice-search.git
cd freeagent-mcp-invoice-search
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set the following environment variables:

- `INVOICE_API_URL` (required): Base URL of your invoice API
- `CF_ACCESS_CLIENT_ID` (required): Cloudflare Access Client ID
- `CF_ACCESS_CLIENT_SECRET` (required): Cloudflare Access Client Secret

### MCP Settings

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "invoice-search": {
      "command": "node",
      "args": ["/absolute/path/to/freeagent-mcp-invoice-search/build/index.js"],
      "env": {
        "INVOICE_API_URL": "https://your-invoice-api.com",
        "CF_ACCESS_CLIENT_ID": "your-cloudflare-client-id",
        "CF_ACCESS_CLIENT_SECRET": "your-cloudflare-client-secret"
      }
    }
  }
}
```

## Usage

Once configured, Claude can search invoices using natural language:

- "Get a summary of invoice INV-011"
- "Show me the full details for invoice 100056"
- "Look up invoice INV145001"

### Tool: get_invoice_summary

Quick lookup returning minimal data for fast reference verification.

**Parameters:**
- `reference` (string, required): The invoice reference number

**Response (~150 bytes):**
```json
{
  "invoices": [
    {
      "id": 123,
      "url": "https://api.freeagent.com/v2/invoices/123",
      "reference": "INV-011"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
```

### Tool: get_invoice_full_details

Complete invoice information including all fields and line items.

**Parameters:**
- `reference` (string, required): The invoice reference number

**Response (~2-10KB):**
```json
{
  "invoices": [
    {
      "id": 123,
      "reference": "INV-011",
      "url": "https://api.freeagent.com/v2/invoices/123",
      "customer_name": "Acme Corp",
      "amount": 1500.00,
      "currency": "GBP",
      "status": "paid",
      "created_at": "2024-01-15",
      "line_items": [...]
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
```

### Other Tools

- **check_health**: Check API health and database connection status
- **get_stats**: Get invoice cache statistics (totals, date ranges, status breakdown)

## API Requirements

Your invoice API must:

- Accept GET requests to `/api/invoices`
- Support `reference` query parameter (string, required)
- Support `include_full_invoice` query parameter (boolean, optional)
  - When false or omitted: return minimal data (id, url, reference)
  - When true: return full invoice JSON with all fields
- Support Cloudflare Access authentication via headers
- Return JSON in the format shown above

## Development

### Build

Compile TypeScript to JavaScript:
```bash
npm run build
```

### Watch Mode

Automatically rebuild on file changes:
```bash
npm run watch
```

### Debugging

The server logs diagnostic information to stderr. You can view these logs in your terminal or MCP client:

```bash
# Run server directly to see logs
export INVOICE_API_URL="https://your-api.com"
export CF_ACCESS_CLIENT_ID="your-client-id"
export CF_ACCESS_CLIENT_SECRET="your-client-secret"
node build/index.js
```

## Project Structure

```
freeagent-mcp-invoice-search/
├── src/
│   ├── types.ts              # TypeScript interfaces
│   ├── mcp-client.ts         # HTTP client
│   └── index.ts              # MCP server
├── build/                    # Compiled JavaScript (generated)
├── .env.example              # Environment variable template
├── CLAUDE.md                 # AI context documentation
├── README.md                 # This file
├── package.json              # NPM configuration
└── tsconfig.json             # TypeScript configuration
```

## Troubleshooting

### Server won't start

- Check that all required environment variables are set
- Verify Node.js version is 18 or higher: `node --version`
- Check file permissions on `build/index.js`
- Review error messages in console output

### No results found

- Verify the invoice reference exists in your system
- Check API credentials are correct
- Review server logs for API errors
- Test API endpoint directly with curl:
  ```bash
  curl -H "CF-Access-Client-Id: your-client-id" \
       -H "CF-Access-Client-Secret: your-client-secret" \
       "https://your-api.com/api/invoices?reference=INV-011"
  ```

### Authentication errors

- Confirm `CF_ACCESS_CLIENT_ID` is valid
- Confirm `CF_ACCESS_CLIENT_SECRET` is valid
- Check API endpoint is accessible from your network
- Verify Cloudflare Access is properly configured on the API

### MCP Integration Issues

- Verify `build/index.js` exists after running `npm run build`
- Check MCP settings JSON is valid
- Restart Claude Desktop after configuration changes
- Review Claude Desktop logs for connection errors

## Technical Details

### Architecture

The server follows a three-layer architecture:

1. **Types Layer** (`types.ts`): TypeScript interfaces for type safety
2. **Client Layer** (`mcp-client.ts`): HTTP client with axios for API communication
3. **Server Layer** (`index.ts`): MCP protocol implementation and tool registration

### Error Handling

- Input validation with clear error messages
- HTTP errors include status codes
- All errors logged to stderr with context
- Graceful handling of API timeouts (30 second timeout)

### Logging

All logs use stderr (stdout is reserved for MCP protocol):

- `[InvoiceCache]` prefix for HTTP client logs
- `[InvoiceSearch]` prefix for server logs
- Structured logging with context objects

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or pull request.

## Related Projects

- [freeagent-mcp](https://github.com/halfords-pro/freeagent-mcp) - Reference MCP server implementation
- [freeagent-invoice-cache](https://github.com/halfords-pro/freeagent-invoice-cache) - Invoice cache API

## Support

For issues and questions:
- Open an issue on GitHub
- Check CLAUDE.md for detailed architecture documentation
- Review the troubleshooting section above