@chaprola/mcp-server 1.13.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)
@@ -911,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.13.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.