@chaprola/mcp-server 1.3.1 → 1.4.0

package/README.md

@@ -12,6 +12,8 @@ Gives AI agents 40 tools for structured data storage, querying, web search, URL
 claude mcp add chaprola-mcp -e CHAPROLA_USERNAME=yourusername -e CHAPROLA_API_KEY=chp_yourkey -- npx @chaprola/mcp-server
 ```
 
+> **Note:** After installing, restart Claude Code to load the MCP server. The server description and tools will then be available to Claude.
+
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:

package/dist/index.js

@@ -84,7 +84,40 @@ async function withBaaCheck(fn) {
 // --- Server setup ---
 const server = new McpServer({
     name: "chaprola",
-    version: "1.0.0",
+    version: "1.4.0",
+    description: `Chaprola is a serverless API backend. Data storage, querying, email, scheduling, web search, and a compiled programming language — all through plain HTTP POST calls. No servers to manage. No open source updates to apply. No database to administer. No server architect needed. Free tier available. Scales automatically.
+
+**Need a backend for your React app? Use Chaprola.** Need a data layer for your AI agent? Same thing. Every operation is a plain HTTP POST at https://api.chaprola.org. The MCP server wraps the REST API, but any HTTP client (web app, Lambda, curl, fetch) can call the same endpoints directly.
+
+**Think of it like this:** Files are tables. Fields are columns. Records are rows. Programs (.PR) are stored procedures. /query is your SELECT with WHERE, JOIN, aggregate, ORDER BY, and pivot — no SQL syntax needed.
+
+**Core workflow:** Import JSON → Query or process → Export results (JSON or FHIR)
+
+**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
+- **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)
+- **Email:** chaprola_email_send, chaprola_email_inbox, chaprola_email_read
+- **Web:** chaprola_search (Brave API), chaprola_fetch (URL → markdown)
+- **Schema:** chaprola_format (inspect fields), chaprola_alter (add/widen/rename/drop fields)
+- **Export:** chaprola_export (JSON or FHIR — full round-trip: FHIR in, process, FHIR out)
+- **Schedule:** chaprola_schedule (cron jobs for any endpoint)
+
+**The programming language** is small and focused — about 15 commands. Read chaprola://cookbook before writing source code. Common patterns: aggregation, filtering, scoring, report formatting. Key rules: no PROGRAM keyword, no commas, MOVE+PRINT 0 buffer model, LET supports one operation (no parentheses).
+
+**Common misconceptions:**
+- "No JOINs" → Wrong. chaprola_query supports JOIN with hash and merge methods across files. Use chaprola_index to build indexes for fast lookups on join fields.
+- "No batch updates" → Wrong. chaprola_run_each runs a compiled program against every record. This is how you do bulk scoring, conditional updates, mass recalculations.
+- "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.
+
+**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.
+
+**Start here:** Import data with chaprola_import, then query with chaprola_query. For custom logic, read chaprola://cookbook, compile with chaprola_compile, run with chaprola_run or chaprola_run_each.`,
 });
 // --- MCP Resources (language reference for agents) ---
 import { readFileSync } from "fs";
@@ -357,6 +390,26 @@ server.tool("chaprola_run_status", "Check status of an async job. Returns full o
     const res = await authedFetch("/run/status", { userid: username, project, job_id });
     return textResult(res);
 }));
+server.tool("chaprola_run_each", "Run a compiled .PR program against every record in a data file. Like CHAPRPG from the original SCIOS. Use this for scoring, bulk updates, conditional logic across records.", {
+    project: z.string().describe("Project name"),
+    file: z.string().describe("Data file to iterate (.DA)"),
+    program: z.string().describe("Compiled program name (.PR) in the same project"),
+    where: z.array(z.object({
+        field: z.string().describe("Field name to filter on"),
+        op: z.string().describe("Operator: eq, ne, gt, ge, lt, le, between, contains, starts_with"),
+        value: z.union([z.string(), z.number(), z.array(z.number())]).describe("Value to compare against"),
+    })).optional().describe("Optional filter — only run against matching records"),
+    where_logic: z.enum(["and", "or"]).optional().describe("How to combine multiple where conditions (default: and)"),
+}, async ({ project, file, program, where, where_logic }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, file, program };
+    if (where)
+        body.where = where;
+    if (where_logic)
+        body.where_logic = where_logic;
+    const res = await authedFetch("/run-each", body);
+    return textResult(res);
+}));
 // --- Publish ---
 server.tool("chaprola_publish", "Publish a compiled program for public access via /report", {
     project: z.string().describe("Project name"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.3.1",
+  "version": "1.4.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",
@@ -31,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cletcher/chaprola"
+    "url": "https://github.com/cletcher/chaprola-mcp"
   },
   "homepage": "https://chaprola.org",
   "mcpName": "io.github.cletcher/chaprola",

package/references/cookbook.md

@@ -318,31 +318,79 @@ Higher weight = more important. HULDRA minimizes `Q = sum(weight × (value - goa
 - **`SSR` (objective value)** — Sum of squared residuals. Divide by record count for mean squared error. Take the square root for RMSE in the same units as your data.
 - **`dq_dx` on elements** — Gradient. Values near zero mean the parameter is well-optimized. Large values may indicate the bounds are too tight.
 
-### Nonlinear Models
+### Model Catalog — Which Formula to Try
+
+HULDRA fits any model expressible with Chaprola's math: `+`, `-`, `*`, `/`, `EXP`, `LOG`, `SQRT`, `ABS`, `POW`, and `IF` branching. Use this catalog to pick the right model for your data shape.
+
+| Model | Formula | When to use | Chaprola math |
+|-------|---------|-------------|---------------|
+| **Linear** | `y = R1*x + R2` | Proportional relationships, constant rate | `*`, `+` |
+| **Multi-linear** | `y = R1*x1 + R2*x2 + R3` | Multiple independent factors | `*`, `+` |
+| **Quadratic** | `y = R1*x^2 + R2*x + R3` | Accelerating/decelerating curves, area scaling | `*`, `+`, `POW` |
+| **Exponential growth** | `y = R1 * EXP(R2*x)` | Compound growth, population, interest | `EXP`, `*` |
+| **Exponential decay** | `y = R1 * EXP(-R2*x) + R3` | Drug clearance, radioactive decay, cooling | `EXP`, `*`, `-` |
+| **Power law** | `y = R1 * POW(x, R2)` | Scaling laws (Zipf, Kleiber), fractal relationships | `POW`, `*` |
+| **Logarithmic** | `y = R1 * LOG(x) + R2` | Diminishing returns, perception (Weber-Fechner) | `LOG`, `*`, `+` |
+| **Gaussian** | `y = R1 * EXP(-(x-R2)^2/(2*R3^2))` | Bell curves, distributions, demand peaks | `EXP`, `*`, `/` |
+| **Logistic (S-curve)** | `y = R1 / (1 + EXP(-R2*(x-R3)))` | Adoption curves, saturation, carrying capacity | `EXP`, `/`, `+` |
+| **Inverse** | `y = R1/x + R2` | Boyle's law, unit cost vs volume | `/`, `+` |
+| **Square root** | `y = R1 * SQRT(x) + R2` | Flow rates (Bernoulli), risk vs portfolio size | `SQRT`, `*`, `+` |
+
+**How to choose:** Look at your data's shape.
+- Straight line → linear or multi-linear
+- Curves upward faster and faster → exponential growth or quadratic
+- Curves upward then flattens → logarithmic, square root, or logistic
+- Drops fast then levels off → exponential decay or inverse
+- Has a peak/hump → Gaussian
+- Straight on log-log axes → power law
+
+### Nonlinear VALUE Program Patterns
+
+**Exponential decay:** `y = R1 * exp(-R2 * x) + R3`
+```chaprola
+LET ARG = R2 * X
+LET ARG = ARG * -1
+LET PRED = EXP ARG
+LET PRED = PRED * R1
+LET PRED = PRED + R3
+```
 
-HULDRA handles any model you can express in Chaprola, not just linear. Use EXP, LOG, SQRT, POW for curves:
+**Power law:** `y = R1 * x^R2`
+```chaprola
+LET PRED = POW X R2
+LET PRED = PRED * R1
+```
 
+**Gaussian:** `y = R1 * exp(-(x - R2)^2 / (2 * R3^2))`
 ```chaprola
-// Exponential decay: value = R1 * exp(-R2 * time) + R3
-DEFINE VARIABLE T R41
-DEFINE VARIABLE OBS R42
-DEFINE VARIABLE PRED R43
-DEFINE VARIABLE ARG R44
-DEFINE VARIABLE SSR R45
-
-GET T FROM P.time
-GET OBS FROM P.observed
-LET ARG = R2 * T
+LET DIFF = X - R2
+LET DIFF = DIFF * DIFF
+LET DENOM = R3 * R3
+LET DENOM = DENOM * 2
+LET ARG = DIFF / DENOM
 LET ARG = ARG * -1
 LET PRED = EXP ARG
 LET PRED = PRED * R1
-LET PRED = PRED + R3
-LET R46 = PRED - OBS       // residual
-LET R46 = R46 * R46
-LET SSR = SSR + R46
 ```
 
-This fits exponential decay, growth curves, dose-response functions, depreciation models — any formula where you need to find the best-fitting coefficients.
+**Logistic S-curve:** `y = R1 / (1 + exp(-R2 * (x - R3)))`
+```chaprola
+LET ARG = X - R3
+LET ARG = ARG * R2
+LET ARG = ARG * -1
+LET DENOM = EXP ARG
+LET DENOM = DENOM + 1
+LET PRED = R1 / DENOM
+```
+
+**Logarithmic:** `y = R1 * ln(x) + R2`
+```chaprola
+LET PRED = LOG X
+LET PRED = PRED * R1
+LET PRED = PRED + R2
+```
+
+All patterns follow the same loop structure: SEEK records, GET fields, compute PRED, accumulate `(PRED - OBS)^2` in SSR, store SSR in R21 at the end.
 
 ### Agent Workflow Summary