# EzzyBills code-generation MCP server

This TypeScript MCP server supplies ChatGPT with the EzzyBills developer
contract needed to generate standalone applications. It is a read-only
knowledge service: it does not call EzzyBills, access customer data, or perform
approval actions at runtime.

## Architecture

```text
ChatGPT
   ↓
get_ezzybills_developer_spec
   ↓
EzzyBills API catalogue, authentication contract, schemas, ID rules,
and generation rules
   ↓
Generated application
   ↓
EzzyBills REST APIs
```

Generated applications run independently of MCP. When they require EzzyBills
access, they authenticate through the Developer Portal credentials:

```text
CLIENT_ID + CLIENT_SECRET
   ↓
POST /oauth/token
   ↓
Authorization: Bearer <token>
   ↓
EzzyBills REST APIs
```

The client secret belongs only in a generated application's backend
environment. It must never be embedded in browser or React code.

## MCP capabilities

The server exposes one MCP tool:

```text
get_ezzybills_developer_spec
```

It returns eleven structured sections:

- `coreArchitecture` — actors and default stack
- `authContract` — OAuth2 client-credentials, token lifecycle
- `universalRules` — rules for all generated applications
- `contentSecurityRules` — HTML sanitization, blob security, sandboxing
- `actionRiskRules` — READ_ONLY / WRITE / DESTRUCTIVE_OR_EXTERNAL classifications
- `apiCatalogue` — 9 verified endpoints including `getPurchaseOrders3`
- `workflowRecipes` — step-by-step recipes for common tasks
- `applicationProfiles` — optional UI blueprints (document-browser, approval-queue, etc.)
- `idRules` — parentDocumentId vs attachmentInvoiceId
- `specificationGaps` — items awaiting backend-developer verification
- `generationRules` — flat compatibility alias

The server also exposes one MCP resource:

```text
ezzybills://docs/developer-spec
```

The resource serves [docs/mcp_api_spec.md](docs/mcp_api_spec.md).

## Requirements

- Node.js 20 or newer
- npm

The MCP server itself does not require EzzyBills account credentials.

## Install and run

```powershell
npm install
npm run dev
```

For a compiled production-style run:

```powershell
npm run build
npm start
```

The default endpoint is:

```text
http://127.0.0.1:3000/mcp
```

The health endpoint is:

```text
http://127.0.0.1:3000/
```

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `HOST` | `127.0.0.1` | Network interface on which the HTTP server listens |
| `PORT` | `3000` | HTTP port |
| `ALLOWED_HOSTS` | local hostnames | Additional accepted HTTP Host header names |
| `ALLOWED_ORIGINS` | local hostnames | Additional accepted Origin header hostnames |

`ALLOWED_HOSTS` and `ALLOWED_ORIGINS` are comma-separated bare hostnames.
Do not include a URL scheme or port.

Example production configuration:

```text
HOST=0.0.0.0
PORT=3000
ALLOWED_HOSTS=mcp.ezzybills.com,<azure-container-app-hostname>
```

Configure `ALLOWED_ORIGINS` only when the connecting client sends an Origin
header. Add the hostname actually used by that client.

Host and Origin validation protect request routing; they are not user
authentication. If the developer specification is not intended to be public,
protect `/mcp` with the authentication or private-ingress arrangement chosen
for the deployment.

## MCP Inspector

1. Start the server with `npm run dev`.
2. Select **Streamable HTTP** in MCP Inspector.
3. Connect to `http://127.0.0.1:3000/mcp`.
4. Confirm the single tool and resource listed above are available.

## Docker

The multi-stage Dockerfile builds the TypeScript source, installs only
production dependencies in the runtime image, and copies the Markdown
specification required by the MCP resource.

```powershell
docker build -t ezzybills-mcp .
docker run --rm -p 3000:3000 -e ALLOWED_HOSTS=localhost ezzybills-mcp
```

For Azure, set the production hostname in `ALLOWED_HOSTS` rather than using
the local Docker value.

## Scripts

| Command | Purpose |
|---|---|
| `npm run dev` | Start the TypeScript server |
| `npm run typecheck` | Type-check source and tests |
| `npm test` | Run the test suite |
| `npm run build` | Compile `src` to `dist` |
| `npm start` | Run the compiled HTTP server |
| `npm run check` | Type-check, test, and build |

## Project layout

```text
docs/mcp_api_spec.md
src/resources/ezzyBillsDeveloperResource.ts
src/tools/getEzzyBillsDeveloperSpec.ts
src/server.ts
src/httpConfig.ts
src/http.ts
test/developerSpec.test.ts
Dockerfile
.dockerignore
```
# TestEzzyBillsMCP