284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
81 lines
2.3 KiB
Markdown
81 lines
2.3 KiB
Markdown
# @alga-psa/mcp-connector
|
|
|
|
A small **local MCP connector** that exposes your AlgaPSA instance to MCP clients
|
|
(Claude Desktop, Cursor, …). It runs on your workstation over **stdio** and acts
|
|
entirely under **your own AlgaPSA API token** — every call inherits your existing
|
|
RBAC/ABAC permissions. There is no agent governance here; your MCP client is the
|
|
human-in-the-loop.
|
|
|
|
## How it works — progressive disclosure
|
|
|
|
Instead of exposing one tool per API endpoint (which would flood the model's
|
|
context), the connector exposes **three constant meta-tools**, regardless of how
|
|
large the AlgaPSA API is:
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `search_api_registry` | Find the right endpoint by natural-language query |
|
|
| `search_business_data` | Find tenant records (tickets, clients, …), ACL-scoped |
|
|
| `call_api_endpoint` | Execute a chosen endpoint by its registry id |
|
|
|
|
The agent searches, reads the one schema it needs, then calls it.
|
|
|
|
## Configuration
|
|
|
|
Two environment variables are required:
|
|
|
|
- `ALGA_INSTANCE_URL` — your AlgaPSA base URL, e.g. `https://alga.example.com`
|
|
- `ALGA_API_TOKEN` — an AlgaPSA API key (Settings → API Keys)
|
|
|
|
Optional: `ALGA_TENANT_ID`, `ALGA_REQUEST_TIMEOUT_MS` (default 30000),
|
|
`ALGA_REGISTRY_PATH` (default `/api/v1/meta/mcp-registry`),
|
|
`ALGA_SEARCH_PATH` (default `/api/v1/search`).
|
|
|
|
### Claude Desktop
|
|
|
|
Add to `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"alga-psa": {
|
|
"command": "npx",
|
|
"args": ["-y", "@alga-psa/mcp-connector"],
|
|
"env": {
|
|
"ALGA_INSTANCE_URL": "https://alga.example.com",
|
|
"ALGA_API_TOKEN": "your-api-key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Cursor
|
|
|
|
Add to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"alga-psa": {
|
|
"command": "npx",
|
|
"args": ["-y", "@alga-psa/mcp-connector"],
|
|
"env": {
|
|
"ALGA_INSTANCE_URL": "https://alga.example.com",
|
|
"ALGA_API_TOKEN": "your-api-key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
ALGA_INSTANCE_URL=https://alga.example.com ALGA_API_TOKEN=key npm run dev -w @alga-psa/mcp-connector
|
|
npm run build -w @alga-psa/mcp-connector # bundles to dist/index.js (npx entry)
|
|
npm test -w @alga-psa/mcp-connector
|
|
```
|
|
|
|
Diagnostics are written to **stderr**; **stdout** carries the MCP JSON-RPC stream.
|