@chaprola/mcp-server 1.12.0 → 1.13.1

package/dist/index.js

@@ -96,7 +96,7 @@ const server = new McpServer({
 **What you can do:**
 - **Import data:** chaprola_import (JSON or FHIR bundles), chaprola_import_download (CSV/Excel/Parquet from URL)
 - **Query data:** chaprola_query (filter, aggregate, join, pivot — like SELECT without SQL)
-- **Record CRUD:** chaprola_insert_record, chaprola_update_record, chaprola_delete_record
+- **Record CRUD:** chaprola_insert_record (single or batch), chaprola_upsert_record (insert-or-update by key), chaprola_update_record, chaprola_delete_record
 - **Batch operations:** chaprola_run_each — run a compiled program against every record in a file (like a stored procedure that executes per-row). Use this for scoring, bulk updates, conditional logic across records.
 - **Compile programs:** chaprola_compile (source code → bytecode). Programs are stored procedures — compile once, run on demand.
 - **Run programs:** chaprola_run (single execution), chaprola_run_each (per-record batch), chaprola_report (published reports)
@@ -119,6 +119,7 @@ const server = new McpServer({
 - "Concurrent writes will conflict" → Wrong. The merge-file model is concurrency-safe with dirty-bit checking. Multiple writers are handled transparently.
 - "Only for AI agents" → Wrong. Every operation is a plain HTTP POST. React, Laravel, Python, curl — any HTTP client works. The MCP server is a convenience wrapper.
 - "Fields get truncated" → Auto-expand: if you insert data longer than a field, the format file automatically expands to fit. No manual schema management needed.
+- "PHI flags can't be removed" → Wrong. Set phi_exempt on the project config via chaprola_config to disable all PHI detection for non-healthcare projects (e.g., video pipelines, task trackers).
 
 **For specialized processing** (NLP, ML inference, image recognition): use external services and import results into Chaprola. Chaprola is the data and compute layer, not the everything layer.
 
@@ -733,6 +734,19 @@ server.tool("chaprola_intent", "Read, write, or delete project and program inten
     const res = await authedFetch("/intent", body);
     return textResult(res);
 });
+// --- Project Config ---
+server.tool("chaprola_config", "Set project configuration. Currently supports phi_exempt (boolean) to disable automatic PHI detection for non-healthcare projects. Fields like step_name, task_name won't be flagged as PHI. Omit phi_exempt to read current config.", {
+    project: z.string().describe("Project name"),
+    phi_exempt: z.boolean().optional().describe("If true, disable all PHI detection and masking for this project. For non-healthcare data only."),
+    userid: z.string().optional().describe("Project owner's username. Defaults to the authenticated user."),
+}, async ({ project, phi_exempt, userid }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: userid || username, project };
+    if (phi_exempt !== undefined)
+        body.phi_exempt = phi_exempt;
+    const res = await authedFetch("/config", body);
+    return textResult(res);
+}));
 // --- Optimize (HULDRA) ---
 server.tool("chaprola_optimize", "Run HULDRA nonlinear optimization using a compiled .PR as the objective evaluator", {
     project: z.string().describe("Project name"),
@@ -897,6 +911,25 @@ server.tool("chaprola_insert_record", "Insert one or more records into a data fi
     const res = await authedFetch("/insert-record", body);
     return textResult(res);
 }));
+server.tool("chaprola_upsert_record", "Insert or update a record by key field. If a record with the matching key value exists, update it. If not, insert it. Batch supported via records array.", {
+    project: z.string().describe("Project name"),
+    file: z.string().describe("Data file name (without extension)"),
+    key: z.string().describe("Field name to match on (must exist in format file)"),
+    record: z.string().optional().describe("JSON object of a single record. Must contain the key field. Use this OR records, not both."),
+    records: z.string().optional().describe("JSON array of records for batch upsert. Each must contain the key field. Use this OR record, not both."),
+    userid: z.string().optional().describe("Project owner's username. Required when accessing a shared project where you are a writer. Defaults to the authenticated user."),
+}, async ({ project, file, key, record: recordStr, records: recordsStr, userid }) => withBaaCheck(async () => {
+    const record = recordStr ? (typeof recordStr === 'string' ? JSON.parse(recordStr) : recordStr) : undefined;
+    const records = recordsStr ? (typeof recordsStr === 'string' ? JSON.parse(recordsStr) : recordsStr) : undefined;
+    const { username } = getCredentials();
+    const body = { userid: userid || username, project, file, key };
+    if (record)
+        body.record = record;
+    if (records)
+        body.records = records;
+    const res = await authedFetch("/upsert-record", body);
+    return textResult(res);
+}));
 server.tool("chaprola_update_record", "Update fields in a single record matched by a where clause. If no sort-key changes, updates in place; otherwise marks old record ignored and appends to merge file.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),

package/package.json

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

package/references/cookbook.md

@@ -271,6 +271,103 @@ LET rec = 1
 
 If the IN-file doesn't exist (e.g., new user), NOT IN treats it as empty — all records pass.
 
+## Batch Insert (Multi-Record Append)
+
+Insert multiple records in a single call:
+
+```bash
+POST /insert-record {
+  userid, project, file: "events",
+  records: [
+    {"event": "login", "ts": "2026-04-09T10:00:00Z"},
+    {"event": "purchase", "ts": "2026-04-09T10:05:00Z"},
+    {"event": "logout", "ts": "2026-04-09T10:30:00Z"}
+  ]
+}
+```
+
+All-or-nothing: if any record has an invalid field, the entire batch is rejected. Max 1000 per call. Single `record: {}` still works for one record.
+
+## UPSERT (Insert or Update)
+
+Create if new, update if exists — one call:
+
+```bash
+POST /upsert-record {
+  userid, project, file: "contacts", key: "contact_id",
+  record: {"contact_id": "c-42", "name": "Alice", "status": "active"}
+}
+```
+
+If a record with `contact_id = "c-42"` exists, update it. If not, insert it. Batch supported via `records: [...]`.
+
+## IN / NOT IN on /query
+
+Filter by a set of values:
+
+```bash
+POST /query {
+  userid, project, file: "orders",
+  where: [{"field": "status", "op": "in", "value": ["active", "pending", "review"]}]
+}
+```
+
+`not_in` excludes values. Empty array: `in` matches nothing, `not_in` matches everything.
+
+## String Transforms on /query
+
+Transform field values at query time without a .CS program:
+
+```bash
+POST /query {
+  userid, project, file: "contacts",
+  select: ["email", "name"],
+  transform: [{"field": "email", "func": "lower"}, {"field": "name", "func": "trim"}]
+}
+```
+
+Functions: `upper`, `lower`, `trim`, `substring` (start, length), `replace` (old, new), `length`. Transforms apply before WHERE evaluation.
+
+## DISTINCT on /query
+
+Return unique rows:
+
+```bash
+POST /query {
+  userid, project, file: "products",
+  select: ["category"],
+  distinct: true
+}
+```
+
+Cannot combine with aggregate or pivot.
+
+## Date Filters on /query
+
+```bash
+# Records from the last 30 days
+POST /query { where: [{"field": "created_at", "op": "date_within", "value": "30d"}] }
+
+# Truncate dates for GROUP BY month (combine with distinct or pivot)
+POST /query { transform: [{"field": "created_at", "func": "date_trunc", "unit": "month"}], distinct: true }
+```
+
+Units for date_trunc: `year`, `month`, `day`, `hour`. Date fields stored as ISO 8601 strings already sort correctly with `gt`, `lt`, `ge`, `le`.
+
+## Parameterized /run
+
+Pass named parameters to /run (same as /report supports):
+
+```bash
+POST /run {
+  userid, project, name: "PROCESS",
+  primary_file: "data",
+  params: {"video_id": "V-AT", "action": "advance"}
+}
+```
+
+Programs read params via `MOVE PARAM.name` or `LET Rn = PARAM.name`. Use /run (not /report) when the program needs to WRITE data.
+
 ## Async for Large Datasets
 
 ```bash

package/references/gotchas.md

@@ -30,16 +30,31 @@ MOVE X.username U.1
 GET R41 FROM P.63 10
 ```
 
-### Use PRINT concatenation, not MOVE + PRINT 0
+### PRINT concatenation requires the + operator between every term
+The `+` is mandatory. Without it, the compiler rejects the code.
 ```chaprola
-// PREFERRED: direct concatenation
-PRINT P.name + " earns $" + R41
-
-// AVOID: old MOVE-to-buffer pattern
-MOVE BLANKS U.1 80
-MOVE P.name U.1 20
-PUT R41 INTO U.22 10 D 2
-PRINT 0
+// CORRECT:
+PRINT "Name: " + P.name + " earns $" + R41
+
+// WRONG — compiler error: "requires + between terms"
+PRINT "Name: " P.name
+PRINT P.name " earns $" R41
+```
+
+MOVE + PRINT 0 still works but is the old style. Prefer PRINT concatenation.
+
+### No commas anywhere in code
+Chaprola has no commas. Not in PRINT, not in function calls, not in lists. Everything is space-separated or uses `+` for concatenation.
+
+### No WHILE, FOR, LOOP, CONTINUE, BREAK, SWITCH, CASE
+These keywords do not exist. Use GOTO with labels for all control flow:
+```chaprola
+LET rec = 1
+100 SEEK rec
+    IF EOF END
+    // ... process ...
+    LET rec = rec + 1
+    GOTO 100
 ```
 
 ### Use CLEAR, not MOVE BLANKS for full regions
@@ -57,6 +72,12 @@ MOVE P.txn_type U.76 6
 IF EQUAL "CREDIT" U.76 GOTO 200
 ```
 
+### IF EQUAL "" is not valid — use IF BLANK
+Comparing against an empty string (`IF EQUAL "" U.1 GOTO 200`) is rejected by the compiler. To test if a field is empty, use `IF BLANK`:
+```chaprola
+IF BLANK P.notes GOTO 200    // field is all spaces/empty
+```
+
 ### MOVE literal auto-pads to field width
 `MOVE "Jones" P.name` auto-fills the rest of the field with blanks. No need to clear first.
 
@@ -107,6 +128,9 @@ Every request body's `userid` must equal your username. 403 on mismatch.
 ### BAA only required for PHI
 The BAA is only needed if your data contains Protected Health Information (patient names, SSNs, dates of birth, etc.). Non-PHI data works without signing a BAA. If you get a 403 on a PHI-flagged field, either sign the BAA or rename the field to avoid PHI auto-detection.
 
+### PHI detection on non-healthcare projects
+If your fields get PHI-flagged incorrectly (e.g., step_name, task_name, video_name), set phi_exempt on the project via `POST /config {"userid": "...", "project": "...", "phi_exempt": true}` or `chaprola_config`. This disables all PHI detection and masking for the project.
+
 ### Async for large datasets
 `POST /run` with `async: true` for >100K records. API Gateway has a 30-second timeout; async bypasses it. Poll `/run/status` until `status: "done"`.