@chaprola/mcp-server 1.5.0 → 1.6.0

package/dist/index.js

@@ -164,6 +164,40 @@ server.resource("endpoints", "chaprola://endpoints", { description: "Chaprola AP
 server.resource("auth", "chaprola://auth", { description: "Chaprola authentication reference — API key model, BAA flow, credential recovery", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://auth", mimeType: "text/markdown", text: readRef("auth.md") }],
 }));
+// --- Modular Resources (Tier 1 + Tier 2) ---
+server.resource("quickstart", "chaprola://quickstart", { description: "Chaprola quickstart — auth, base URL, core workflow, and index of all feature references. READ THIS FIRST.", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://quickstart", mimeType: "text/markdown", text: readRef("quickstart.md") }],
+}));
+server.resource("ref-import", "chaprola://ref/import", { description: "Import, export, list, download — all data I/O endpoints", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/import", mimeType: "text/markdown", text: readRef("ref-import.md") }],
+}));
+server.resource("ref-query", "chaprola://ref/query", { description: "Query, sort, index, merge, record CRUD — data operations", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/query", mimeType: "text/markdown", text: readRef("ref-query.md") }],
+}));
+server.resource("ref-pivot", "chaprola://ref/pivot", { description: "Pivot tables (GROUP BY) — row, column, aggregate functions", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/pivot", mimeType: "text/markdown", text: readRef("ref-pivot.md") }],
+}));
+server.resource("ref-mercury", "chaprola://ref/mercury", { description: "Mercury weighted scoring — rank records by multiple criteria", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/mercury", mimeType: "text/markdown", text: readRef("ref-mercury.md") }],
+}));
+server.resource("ref-programs", "chaprola://ref/programs", { description: "Chaprola .CS language — MOVE, LET, GET, PUT, SEEK, IF, GOTO, PRINT, secondary files, params", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/programs", mimeType: "text/markdown", text: readRef("ref-programs.md") }],
+}));
+server.resource("ref-huldra", "chaprola://ref/huldra", { description: "HULDRA nonlinear optimization — parameter fitting, model catalog", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/huldra", mimeType: "text/markdown", text: readRef("ref-huldra.md") }],
+}));
+server.resource("ref-deploy", "chaprola://ref/deploy", { description: "Static app deployment to chaprola.org/apps/", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/deploy", mimeType: "text/markdown", text: readRef("ref-deploy.md") }],
+}));
+server.resource("ref-email", "chaprola://ref/email", { description: "Email system — inbox, read, send, forward, attachments", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/email", mimeType: "text/markdown", text: readRef("ref-email.md") }],
+}));
+server.resource("ref-gotchas", "chaprola://ref/gotchas", { description: "Common Chaprola mistakes — language, API, and secondary file pitfalls", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/gotchas", mimeType: "text/markdown", text: readRef("ref-gotchas.md") }],
+}));
+server.resource("ref-auth", "chaprola://ref/auth", { description: "Authentication details — registration, login, BAA, MCP env vars", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/auth", mimeType: "text/markdown", text: readRef("ref-auth.md") }],
+}));
 // --- MCP Prompts ---
 server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read this before writing any Chaprola source code.", async () => ({
     messages: [{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents 46 tools for structured data storage, record CRUD, querying, schema inspection, web search, URL fetching, scheduled jobs, and execution via plain HTTP.",
   "type": "module",
   "main": "dist/index.js",

package/references/quickstart.md

@@ -0,0 +1,30 @@
+# Chaprola Quickstart
+
+Base URL: `https://api.chaprola.org`
+Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
+Every request body's `userid` must match the authenticated username.
+
+## Core Workflow
+
+```bash
+POST /import {userid, project, name: "STAFF", data: [{name: "Alice", salary: 95000}, ...]}
+POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "STAFF"}
+POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
+```
+
+## Available References
+
+Read only what your app needs:
+
+| Resource | When to read |
+|----------|-------------|
+| `chaprola://ref/import` | Importing data, exporting, listing files |
+| `chaprola://ref/query` | Filtering, sorting, indexing, joining data |
+| `chaprola://ref/pivot` | GROUP BY / pivot tables |
+| `chaprola://ref/mercury` | Weighted scoring / ranking |
+| `chaprola://ref/programs` | Writing .CS source code (MOVE, LET, GET, PUT, SEEK, IF, GOTO, PRINT) |
+| `chaprola://ref/huldra` | Nonlinear optimization / parameter fitting |
+| `chaprola://ref/deploy` | Deploying static web apps to chaprola.org/apps/ |
+| `chaprola://ref/email` | Sending/receiving email via @chaprola.org |
+| `chaprola://ref/gotchas` | Common mistakes to avoid |
+| `chaprola://ref/auth` | Registration, login, BAA, credentials |

package/references/ref-auth.md

@@ -0,0 +1,25 @@
+# Authentication
+
+## API Key Model
+All protected requests: `Authorization: Bearer chp_your_api_key`
+Keys: `chp_` + 64 hex chars. Expire after 90 days.
+
+## Registration & Login
+```bash
+POST /register {"username": "my-agent", "passcode": "16-chars-minimum-passcode"}
+→ {"api_key": "chp_..."}
+
+POST /login {"username": "my-agent", "passcode": "..."}
+→ {"api_key": "chp_..."}  # old keys remain valid until expiration
+```
+- Passcode: 16-128 chars. Username: 3-40 chars, alphanumeric + hyphens/underscores.
+- Rate limits: auth 5 rps, data 20 rps.
+
+## BAA
+Only needed for PHI. Sign once: `POST /baa-text` → human reviews → `POST /sign-baa {userid, signatory_name}`.
+
+## MCP Environment Variables
+| Variable | Description |
+|----------|-------------|
+| `CHAPROLA_USERNAME` | Your registered username |
+| `CHAPROLA_API_KEY` | Your API key (`chp_...`) |

package/references/ref-deploy.md

@@ -0,0 +1,24 @@
+# App Deployment
+
+Deploy static web apps (HTML/JS/CSS) to `https://chaprola.org/apps/{userid}/{project}/`.
+
+## Flow
+```bash
+# 1. Get presigned upload URL
+POST /app/deploy {userid, project} → {upload_url, staging_key, max_size_mb: 50}
+
+# 2. Upload .zip or .tar.gz to upload_url
+PUT upload_url --data-binary @app.zip
+
+# 3. Extract and deploy
+POST /app/deploy/process {userid, project, staging_key} → {url, files_deployed}
+```
+
+## Single file upload
+```bash
+POST /app/upload {userid, project, path: "css/app.css"} → {upload_url, content_type}
+PUT upload_url --data-binary @app.css
+```
+
+Max 500 files per app. Blocked extensions: .php, .py, .sh, .exe.
+Content-Type set automatically from extension.

package/references/ref-email.md

@@ -0,0 +1,20 @@
+# Email (@chaprola.org)
+
+Every account gets `{username}@chaprola.org`.
+
+## Endpoints
+- `POST /email/inbox {address, limit?, before?}` → `{emails: [...], total}`
+- `POST /email/read {address, message_id}` → `{email: {from, to, subject, text, html, attachments}}`
+- `POST /email/send {from, to, subject, text, html?}` → `{status, message_id}`
+- `POST /email/delete {address, message_id}` → `{status}`
+- `POST /email/forward {from, message_id, to}` → `{status, resend_message_id}`
+
+## Attachments
+`/email/read` returns presigned download URLs (1hr expiry) for each attachment.
+`/email/forward` re-attaches stored attachments automatically.
+
+## Rate limits
+20 emails/day per user, 3 emails/minute. Outbound emails are AI content-moderated (blocks spam/PHI).
+
+## Delegates
+Agents can send as another user if listed in their delegate file. E.g., tawni can send `"from": "charles"`.

package/references/ref-gotchas.md

@@ -0,0 +1,23 @@
+# Gotchas
+
+## Language
+- **No parentheses in LET.** `LET result = price * qty` only. For `price * (qty + bonus)`: use `LET temp = qty + bonus` then `LET result = price * temp`.
+- **IF EQUAL compares literal to location.** To compare two locations, copy both to U buffer first.
+- **MOVE length must match field width.** If `name` is 8 chars wide, `MOVE P.name U.1 20` bleeds into adjacent fields.
+- **DEFINE VARIABLE names must not collide with field names.** If format has `balance`, don't `DEFINE VARIABLE balance R41`.
+- **R-variables are 64-bit floats.** `7 / 2 = 3.5`. Use PUT with `I` format for integer display.
+- **FIND returns 0 on no match.** Always check `IF match EQ 0` before READ.
+- **PRINT 0 clears the U buffer.** No need to manually clear between prints.
+- **Statement numbers are labels, not line numbers.** Only number GOTO/CALL targets.
+
+## API
+- **userid must match authenticated user.** 403 on mismatch.
+- **Login invalidates the old key.** Save the new one immediately.
+- **Async for large datasets.** `/run` with `async: true` for >100K records (API Gateway 30s timeout).
+- **secondary_format is a string**, not an array.
+- **Data files expire.** Default 90 days. Override with `expires_in_days` on import.
+- **API keys expire after 90 days.** Re-login to get a new key.
+
+## Secondary Files
+- **One at a time.** CLOSE before opening another.
+- **CLOSE flushes writes.** Always CLOSE before END if you wrote to the secondary file.

package/references/ref-huldra.md

@@ -0,0 +1,78 @@
+# HULDRA — Nonlinear Optimization
+
+HULDRA finds optimal parameter values for a mathematical model by minimizing the difference between predictions and observed data.
+
+## R-Variable Interface
+
+| Range | Purpose | Who sets it |
+|-------|---------|-------------|
+| R1–R20 | Elements (parameters to optimize) | HULDRA sets before each run |
+| R21–R40 | Objectives (error metrics) | Your program computes these |
+| R41–R50 | Scratch space | Your program's temp variables |
+
+## POST /optimize
+```json
+{
+  "userid": "...", "project": "fit", "program": "SALFIT", "primary_file": "EMP",
+  "elements": [
+    {"index": 1, "label": "slope", "start": 5000, "min": 0, "max": 20000, "delta": 10},
+    {"index": 2, "label": "base", "start": 40000, "min": 0, "max": 100000, "delta": 100}
+  ],
+  "objectives": [
+    {"index": 1, "label": "SSR", "goal": 0.0, "weight": 1.0}
+  ],
+  "max_iterations": 100,
+  "async_exec": true
+}
+```
+
+Async: `POST /optimize/status {userid, project, job_id}`
+
+## Delta Guidance
+- Dollar amounts: `0.01` to `1.0`
+- Rates/percentages: `0.001` to `0.01`
+- Counts: `0.1` to `1.0`
+
+## Performance
+HULDRA runs your program `1 + 2 × N_elements` times per iteration. Lambda timeout: 900s. Sample large datasets (200-500 records) before optimizing.
+
+## Complete Example: Linear Fit
+`salary = R1 × years_exp + R2`
+
+```chaprola
+DEFINE VARIABLE REC R41
+DEFINE VARIABLE YRS R42
+DEFINE VARIABLE SAL R43
+DEFINE VARIABLE PRED R44
+DEFINE VARIABLE RESID R45
+DEFINE VARIABLE SSR R46
+
+LET SSR = 0          // MUST initialize to 0
+LET REC = 1
+100 SEEK REC
+    IF EOF GOTO 200
+    GET YRS FROM P.years_exp
+    GET SAL FROM P.salary
+    LET PRED = R1 * YRS
+    LET PRED = PRED + R2
+    LET RESID = PRED - SAL
+    LET RESID = RESID * RESID
+    LET SSR = SSR + RESID
+    LET REC = REC + 1
+    GOTO 100
+200 LET R21 = SSR
+    END
+```
+
+## Model Catalog
+
+| Model | Formula | When to use |
+|-------|---------|-------------|
+| Linear | `y = R1*x + R2` | Proportional relationships |
+| Multi-linear | `y = R1*x1 + R2*x2 + R3` | Multiple factors |
+| Quadratic | `y = R1*x^2 + R2*x + R3` | Accelerating curves |
+| Exponential | `y = R1 * EXP(R2*x)` | Compound growth |
+| Exp. decay | `y = R1 * EXP(-R2*x) + R3` | Decay, cooling |
+| Power law | `y = R1 * POW(x, R2)` | Scaling laws |
+| Logarithmic | `y = R1 * LOG(x) + R2` | Diminishing returns |
+| Logistic | `y = R1 / (1 + EXP(-R2*(x-R3)))` | S-curves, saturation |

package/references/ref-import.md

@@ -0,0 +1,34 @@
+# Import / Export / Files
+
+## POST /import
+`{userid, project, name, data: [{...}, ...], format?, expires_in_days?, force?}`
+Returns: `{records, fields, record_length, format_file, data_file}`
+
+```bash
+POST /import {userid, project, name: "STAFF", data: [{"name": "Alice", "salary": 95000}]}
+```
+
+Field widths auto-sized from longest value. Default expiry: 90 days. Override with `expires_in_days`.
+
+## Large File Upload (presigned URL)
+```bash
+POST /import-url {userid, project, name} → {upload_url, staging_key}
+# PUT your JSON to upload_url
+POST /import-process {userid, project, name, staging_key} → same as /import
+```
+
+## POST /import-download
+`{userid, project, name, url, instructions?, max_rows?}`
+Imports directly from URL. Supports: CSV, TSV, JSON, NDJSON, Parquet, Excel (.xlsx/.xls).
+Optional `instructions` for AI schema inference. Max 1M records.
+
+## POST /export
+`{userid, project, name, format?}` → `{data: [...records]}`
+Optional `format: "fhir"` for FHIR JSON reconstruction.
+
+## POST /list
+`{userid, project, pattern?}` → `{files: [...], total}`
+
+## POST /download
+`{userid, project, file, type}` → `{download_url, expires_in, size_bytes}`
+Type: `data`, `format`, `source`, `proc`, `output`.

package/references/ref-mercury.md

@@ -0,0 +1,23 @@
+# Mercury (Weighted Scoring)
+
+Add `mercury` to `/query` to score and rank records by weighted criteria.
+
+```json
+POST /query {
+  "userid": "...", "project": "...", "file": "CANDIDATES",
+  "mercury": {
+    "scores": [
+      {"field": "experience_years", "weight": 0.4, "direction": "higher_better"},
+      {"field": "interview_score", "weight": 0.35, "direction": "higher_better"},
+      {"field": "salary_ask", "weight": 0.25, "direction": "lower_better"}
+    ]
+  },
+  "limit": 10
+}
+```
+
+Returns records ranked by composite score (0-100). Each record includes `_mercury_score` and per-field `_mercury_{field}` component scores.
+
+Fields are normalized min-max within the dataset. `direction` controls whether higher or lower raw values score better. Weights must sum to 1.0.
+
+Combine with `where` to pre-filter before scoring.

package/references/ref-pivot.md

@@ -0,0 +1,32 @@
+# Pivot (GROUP BY)
+
+Chaprola's pivot IS GROUP BY. Add `pivot` to `/query`.
+
+## Simple aggregation (no cross-tab)
+```json
+POST /query {
+  "userid": "...", "project": "...", "file": "STAFF",
+  "pivot": {
+    "row": "department",
+    "column": "",
+    "values": [
+      {"field": "department", "function": "count"},
+      {"field": "salary", "function": "avg"}
+    ]
+  }
+}
+```
+SQL equivalent: `SELECT department, COUNT(*), AVG(salary) FROM staff GROUP BY department`
+
+## Cross-tabulation
+```json
+"pivot": {
+  "row": "department",
+  "column": "year",
+  "values": [{"field": "revenue", "function": "sum"}],
+  "totals": true
+}
+```
+SQL equivalent: `SELECT department, year, SUM(revenue) FROM sales GROUP BY department, year`
+
+Supported functions: `count`, `sum`, `avg`, `min`, `max`, `stddev`.

package/references/ref-programs.md

@@ -0,0 +1,85 @@
+# Chaprola Programs (.CS Source)
+
+## Compile & Run
+```bash
+POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "STAFF", secondary_format?: "DEPTS"}
+POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1, async?: true, nophi?: true}
+POST /run/status {userid, project, job_id}  # poll async jobs
+POST /publish {userid, project, name, primary_file, acl?: "public|authenticated|owner|token"}
+```
+
+## Memory Regions
+
+| Prefix | Description |
+|--------|-------------|
+| `P` | Primary data file (current record) |
+| `S` | Secondary data file (current record) |
+| `U` | User buffer (output scratch) |
+| `X` | System text (date, time, filenames) |
+
+## Language Essentials
+
+```chaprola
+// Loop through records
+DEFINE VARIABLE rec R41
+LET rec = 1
+100 SEEK rec
+    IF EOF GOTO 900
+    MOVE P.name U.1 20          // copy field to output buffer
+    GET sal FROM P.salary        // numeric field → R variable
+    PUT sal INTO U.22 10 D 2     // R variable → formatted output
+    PRINT 0                      // output full U buffer, clear it
+    LET rec = rec + 1
+    GOTO 100
+900 END
+```
+
+- `PRINT 0` — output entire U buffer and clear. `PRINT N` — output exactly N chars.
+- `MOVE BLANKS U.1 80` — clear a region. `MOVE "literal" U.1 7` — move literal.
+- `IF EQUAL "text" U.50 4 GOTO 200` — compare literal to memory location.
+- `U.name` — named positions (auto-allocated by compiler): `MOVE P.name U.name 20`
+- `DEFINE VARIABLE counter R41` — alias R-variable. **Use R41-R50** (R1-R40 reserved for HULDRA).
+
+## PUT Format Codes
+
+| Code | Description | Example |
+|------|-------------|---------|
+| `D` | Dollar with commas | `$1,234.56` |
+| `F` | Fixed decimal | `1234.56` |
+| `I` | Integer (right-justified) | `  1234` |
+| `E` | Scientific notation | `1.23E+03` |
+
+Syntax: `PUT R41 INTO U.30 10 D 2` — (R-var, location, width, format, decimals)
+
+## Math
+
+```chaprola
+LET R42 = R41 + 1       // one operation per LET
+LET R43 = EXP R41       // also: LOG, SQRT, ABS
+LET R44 = POW R41 R42   // R41^R42
+```
+
+## Secondary Files (FIND/JOIN)
+
+```chaprola
+OPEN "DEPARTMENTS" 0              // open secondary file
+FIND match FROM S.dept_code 3 USING P.dept_code
+IF match EQ 0 GOTO 200           // 0 = no match
+READ match                        // load matched record
+MOVE S.dept_name U.30 15
+WRITE match                       // write back if modified
+CLOSE                             // flush + close
+```
+
+Compile with: `secondary_format: "DEPARTMENTS"`
+
+## Parameterized Reports (PARAM.name)
+```chaprola
+MOVE PARAM.deck U.1 20           // string param → U buffer
+LET lvl = PARAM.level            // numeric param → R variable
+```
+Publish, then call: `POST /report?userid=X&project=Y&name=Z&deck=kanji&level=3`
+Discover params: `POST /report/params {userid, project, name}`
+
+## Common Field Widths
+ISO datetime: 20, UUID: 36, email: 50, short ID: 8-12, dollar: 10, phone: 15.

package/references/ref-query.md

@@ -0,0 +1,40 @@
+# Query / Sort / Index / Merge
+
+## POST /query
+```json
+{
+  "userid": "...", "project": "...", "file": "STAFF",
+  "where": [{"field": "salary", "op": "gt", "value": 80000}],
+  "where_logic": "and",
+  "select": ["name", "salary"],
+  "aggregate": [{"field": "salary", "function": "avg"}],
+  "order_by": "salary desc",
+  "limit": 100,
+  "offset": 0
+}
+```
+Returns: `{records: [...], total, fields}`
+
+WHERE operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`, `contains`, `starts_with`, `ends_with`
+
+## JOIN
+Add `join` to /query:
+```json
+"join": {"file": "DEPARTMENTS", "on": {"left": "dept_id", "right": "dept_id"}, "type": "inner"}
+```
+Types: `inner`, `left`, `right`, `full`. Optional `pre_sorted: true` for merge join.
+
+## POST /sort
+`{userid, project, file, sort_by: "salary desc"}`
+
+## POST /index
+`{userid, project, file, key_fields: ["dept_id"], output: "STAFF_BY_DEPT"}`
+
+## POST /merge
+`{userid, project, file_a, file_b, output, key}`
+
+## Record CRUD
+- `POST /insert-record {userid, project, file, record: {field: "value"}}`
+- `POST /update-record {userid, project, file, where: [...], set: {field: "value"}}`
+- `POST /delete-record {userid, project, file, where: [...]}`
+- `POST /consolidate {userid, project, file}` — merge .MRG into .DA