@chaprola/mcp-server 1.13.0 → 1.14.0

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)"),
@@ -935,25 +954,6 @@ server.tool("chaprola_delete_record", "Delete a single record matched by a where
     const res = await authedFetch("/delete-record", { userid: userid || username, project, file, where: whereClause });
     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 in place. If not, insert it. Supports batch: pass records array to upsert multiple records in one call.", {
-    project: z.string().describe("Project name"),
-    file: z.string().describe("Data file name (without extension)"),
-    key: z.string().describe("Field name to match on, e.g. \"contact_id\". Must exist in the format file."),
-    record: z.string().optional().describe("JSON object of a single record to upsert, e.g. {\"contact_id\": \"c-42\", \"name\": \"Alice\"}. Must contain the key field. Use this OR records, not both."),
-    records: z.string().optional().describe("JSON array of records for batch upsert (max 1000). 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_consolidate", "Merge a .MRG file into its parent .DA, producing a clean sorted data file. Deletes .MRG and .IGN after success. Aborts if .MRG was modified during the operation.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
@@ -1024,6 +1024,45 @@ server.tool("chaprola_app_upload", "Get a presigned URL to upload a single file
     const res = await authedFetch("/app/upload", { userid: username, project, path });
     return textResult(res);
 }));
+server.tool("chaprola_app_upload_inline", "Upload a single file's contents inline (no presigned PUT, no curl step). Use this for hot-fixes to one HTML/JS/CSS file. Max 3 MB raw payload. For larger files, use chaprola_app_upload.", {
+    project: z.string().describe("Project name for the app"),
+    path: z.string().describe("File path within the app (e.g. 'css/app.css', 'results.html')"),
+    content: z.string().describe("File contents. Plain text by default; pass encoding='base64' for binary files."),
+    encoding: z.enum(["text", "base64"]).optional().describe("Content encoding: 'text' (default) or 'base64' for binary files"),
+    content_type: z.string().optional().describe("MIME type override. Inferred from path extension if omitted."),
+    userid: z.string().optional().describe("Project owner's username. Required when deploying to a shared project where you are a writer. Defaults to the authenticated user."),
+}, async ({ project, path, content, encoding, content_type, userid }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = {
+        userid: userid || username,
+        project,
+        path,
+        content,
+    };
+    if (encoding)
+        body.encoding = encoding;
+    if (content_type)
+        body.content_type = content_type;
+    const res = await authedFetch("/app/upload/inline", body);
+    return textResult(res);
+}));
+server.tool("chaprola_app_deploy_inline", "Deploy a base64-encoded tar.gz or zip archive in one call — no presigned PUT, no curl step. Max 3 MB raw (~4 MB base64). For larger bundles use chaprola_app_deploy.", {
+    project: z.string().describe("Project name for the app"),
+    archive: z.string().describe("Base64-encoded tar.gz or zip archive of the app directory"),
+    archive_format: z.enum(["tar.gz", "zip"]).optional().describe("Archive format. Auto-detected from magic bytes if omitted."),
+    userid: z.string().optional().describe("Project owner's username. Required when deploying to a shared project where you are a writer. Defaults to the authenticated user."),
+}, async ({ project, archive, archive_format, userid }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = {
+        userid: userid || username,
+        project,
+        archive,
+    };
+    if (archive_format)
+        body.archive_format = archive_format;
+    const res = await authedFetch("/app/deploy/inline", body);
+    return textResult(res);
+}));
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "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.