@chaprola/mcp-server 1.4.2 → 1.5.0

package/dist/index.js

@@ -695,6 +695,14 @@ server.tool("chaprola_email_delete", "Delete a specific email from your mailbox"
     const res = await authedFetch("/email/delete", { address: username, message_id });
     return textResult(res);
 }));
+server.tool("chaprola_email_forward", "Forward an email (with attachments) to another address. Reads the original email from your mailbox, includes all attachments, and sends via Resend.", {
+    message_id: z.string().describe("Message ID of the email to forward"),
+    to: z.string().describe("Destination email address"),
+}, async ({ message_id, to }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/email/forward", { from: username, message_id, to });
+    return textResult(res);
+}));
 // --- Search ---
 server.tool("chaprola_search", "Search the web via Brave Search API. Returns titles, URLs, and snippets. Optional AI-grounded summary. Rate limit: 10/day per user", {
     query: z.string().describe("Search query string"),
@@ -784,6 +792,57 @@ server.tool("chaprola_consolidate", "Merge a .MRG file into its parent .DA, prod
     const res = await authedFetch("/consolidate", { userid: username, project, file });
     return textResult(res);
 }));
+// --- Site Keys ---
+server.tool("chaprola_create_site_key", "Create an origin-locked site key for frontend JavaScript. Site keys are restricted to specific origins and endpoints, safe to embed in public code.", {
+    label: z.string().describe("Human-readable label for this key (e.g., 'poll-frontend')"),
+    allowed_origins: z.array(z.string()).describe("HTTPS URL patterns where this key works (e.g., ['https://chaprola.org/apps/poll/*']). Wildcards allowed at end."),
+    allowed_endpoints: z.array(z.string()).describe("API endpoints this key can call (e.g., ['/query', '/insert-record', '/report']). Security-sensitive endpoints like /export, /import, /compile are always denied."),
+}, async ({ label, allowed_origins, allowed_endpoints }) => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/create-site-key", {
+        userid: username,
+        label,
+        allowed_origins,
+        allowed_endpoints,
+    });
+    return textResult(res);
+});
+server.tool("chaprola_list_site_keys", "List all site keys for the authenticated user. Shows label, allowed origins/endpoints, and creation date.", {}, async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/list-site-keys", { userid: username });
+    return textResult(res);
+});
+server.tool("chaprola_delete_site_key", "Delete a site key. Requires the full site key value (site_...).", {
+    site_key: z.string().describe("The full site key to delete (starts with site_)"),
+}, async ({ site_key }) => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/delete-site-key", { userid: username, site_key });
+    return textResult(res);
+});
+// --- App Hosting tools ---
+server.tool("chaprola_app_deploy", "Deploy a static web app (HTML/JS/CSS) to chaprola.org/apps/{userid}/{project}/. Returns a presigned upload URL for a .zip or .tar.gz archive.", {
+    project: z.string().describe("Project name for the app"),
+}, async ({ project }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/deploy", { userid: username, project });
+    return textResult(res);
+}));
+server.tool("chaprola_app_deploy_process", "Process a staged app archive and deploy files to chaprola.org/apps/{userid}/{project}/", {
+    project: z.string().describe("Project name for the app"),
+    staging_key: z.string().describe("Staging key returned by chaprola_app_deploy"),
+}, async ({ project, staging_key }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/deploy/process", { userid: username, project, staging_key });
+    return textResult(res);
+}));
+server.tool("chaprola_app_upload", "Get a presigned URL to upload a single file to a deployed app at chaprola.org/apps/{userid}/{project}/{path}", {
+    project: z.string().describe("Project name for the app"),
+    path: z.string().describe("File path within the app (e.g. 'css/app.css', 'index.html')"),
+}, async ({ project, path }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/upload", { userid: username, project, path });
+    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.4.2",
+  "version": "1.5.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/auth.md

@@ -33,16 +33,14 @@ POST /login {"username": "my-agent", "passcode": "a-long-secure-passcode-16-char
 
 ## BAA (Business Associate Agreement)
 
-All data endpoints require a signed BAA. Without it, requests return 403.
+**Only needed for PHI (Protected Health Information).** Non-PHI data works without a BAA. If your data contains no patient names, SSNs, dates of birth, or other HIPAA identifiers, skip the BAA entirely.
 
-**Flow:**
+If you do handle PHI, sign the BAA once per account:
 1. `POST /baa-text` → get BAA text (show to human)
 2. Human reviews and agrees
 3. `POST /sign-baa` → sign it (one-time per account)
 4. `POST /baa-status` → verify signing status
 
-**Exempt endpoints** (no BAA required): /hello, /register, /login, /check-username, /delete-account, /sign-baa, /baa-status, /baa-text, /report, /email/inbound
-
 ## MCP Server Environment Variables
 
 | Variable | Description |

package/references/cookbook.md

@@ -13,6 +13,30 @@ POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "
 POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
 ```
 
+## R-Variable Ranges
+
+| Range | Purpose | Safe for DEFINE VARIABLE? |
+|-------|---------|--------------------------|
+| R1–R20 | HULDRA elements (parameters) | No — HULDRA overwrites these |
+| R21–R40 | HULDRA objectives (error metrics) | No — HULDRA reads these |
+| R41–R50 | Scratch space | **Yes — always use R41–R50 for DEFINE VARIABLE** |
+
+For non-HULDRA programs, R1–R40 are technically available but using R41–R50 is a good habit.
+
+## PRINT: Output from U Buffer
+
+```
+PRINT 0   — output the ENTIRE U buffer contents, then clear it
+PRINT N   — output exactly N characters from U buffer (no clear)
+```
+
+Use `PRINT N` when you've placed data at specific positions and want clean output without trailing garbage. Use `PRINT 0` for quick output of everything.
+
+```chaprola
+MOVE "Hello" U.1 5
+PRINT 5    // Outputs "Hello" — exactly 5 chars, no trailing spaces
+```
+
 ## Hello World (no data file)
 
 ```chaprola
@@ -58,7 +82,25 @@ READ match                   // load matched secondary record
 MOVE S.dept_name U.12 15    // now accessible
 ```
 
-Compile with: `primary_format: "EMPLOYEES", secondary_format: "DEPARTMENTS"`
+Compile with both formats so the compiler resolves fields from both files:
+```bash
+POST /compile {
+  userid, project, name: "REPORT",
+  source: "...",
+  primary_format: "EMPLOYEES",
+  secondary_format: "DEPARTMENTS"
+}
+```
+
+## Comparing Two Memory Locations
+
+IF EQUAL compares a literal to a location. To compare two memory locations, copy both to U buffer:
+
+```chaprola
+MOVE PARAM.poll_id U.200 12
+MOVE P.poll_id U.180 12
+IF EQUAL U.200 U.180 12 GOTO 200   // match — jump to handler
+```
 
 ## Read-Modify-Write (UPDATE)
 
@@ -83,6 +125,90 @@ POST /run/status {userid, project, job_id}
 # Response: {status: "done", output: "..."}
 ```
 
+## Parameterized Reports (PARAM.name)
+
+Programs can accept named parameters from URL query strings. Use this for dynamic reports.
+
+```chaprola
+// Report that accepts &deck=kanji&level=3 as URL params
+MOVE PARAM.deck U.1 20       // string param → U buffer
+LET lvl = PARAM.level        // numeric param → R variable
+SEEK 1
+100 IF EOF GOTO 900
+    MOVE P.deck U.30 10
+    IF EQUAL PARAM.deck U.30 GOTO 200   // filter by deck param
+    GOTO 300
+200 GET cardlvl FROM P.level
+    IF cardlvl NE lvl GOTO 300           // filter by level param
+    MOVE P.kanji U.1 4
+    MOVE P.reading U.6 10
+    PRINT 0
+300 LET rec = rec + 1
+    SEEK rec
+    GOTO 100
+900 END
+```
+
+Publish with: `POST /publish {userid, project, name, primary_file, acl: "authenticated"}`
+Call with: `GET /report?userid=X&project=Y&name=Z&deck=kanji&level=3`
+Discover params: `POST /report/params {userid, project, name}` → returns .PF schema (field names, types, widths)
+
+## Named Output Positions (U.name)
+
+Instead of `U.1`, `U.12`, etc., use named positions for readable code:
+
+```chaprola
+// U.name positions are auto-allocated by the compiler
+MOVE P.name U.name 20
+MOVE P.dept U.dept 10
+PUT sal INTO U.salary 10 D 0
+PRINT 0
+```
+
+## GROUP BY with Pivot (via /query)
+
+Chaprola's pivot IS GROUP BY. Set `row` = grouping field, `values` = aggregate functions.
+
+```bash
+# SQL: SELECT department, COUNT(*), AVG(salary) FROM staff GROUP BY department
+POST /query {
+  userid, project, file: "STAFF",
+  pivot: {
+    row: "department",
+    values: [
+      {field: "department", function: "count"},
+      {field: "salary", function: "avg"}
+    ]
+  }
+}
+
+# SQL: SELECT department, year, SUM(revenue) FROM sales GROUP BY department, year
+POST /query {
+  userid, project, file: "SALES",
+  pivot: {
+    row: "department",
+    column: "year",
+    values: [{field: "revenue", function: "sum"}],
+    totals: true
+  }
+}
+```
+
+For simple aggregation without a cross-tabulation column, set `column` to empty string:
+```bash
+# Count records per department (no cross-tab)
+POST /query {
+  userid, project, file: "STAFF",
+  pivot: {
+    row: "department",
+    column: "",
+    values: [{field: "department", function: "count"}]
+  }
+}
+```
+
+Supported aggregate functions: `count`, `sum`, `avg`, `min`, `max`, `stddev`.
+
 ## PUT Format Codes
 
 | Code | Description | Example |
@@ -94,6 +220,19 @@ POST /run/status {userid, project, job_id}
 
 Syntax: `PUT R1 INTO U.30 10 D 2` (R-var, location, width, format, decimals)
 
+## Common Field Widths
+
+| Data type | Chars | Example |
+|-----------|-------|---------|
+| ISO datetime | 20 | `2026-03-28T14:30:00Z` |
+| UUID | 36 | `550e8400-e29b-41d4-a716-446655440000` |
+| Email | 50 | `user@example.com` |
+| Short ID | 8–12 | `poll_001` |
+| Dollar amount | 10 | `$1,234.56` |
+| Phone | 15 | `+1-555-123-4567` |
+
+Use these when sizing MOVE lengths and U buffer positions.
+
 ## Memory Regions
 
 | Prefix | Description |

package/references/endpoints.md

@@ -14,7 +14,7 @@ Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
 | `POST /check-username` | `{username}` → `{available: bool}` |
 | `POST /delete-account` | `{username, passcode}` → deletes account + all data |
 | `POST /baa-text` | `{}` → `{baa_version, text}`. Get BAA for human review |
-| `POST /report` | `{userid, project, name}` → program output. Program must be published |
+| `POST /report` | `{userid, project, name, &param=value}` → program output. Accepts named params via URL query strings. Use `/report/params` to discover schema. Program must be published |
 
 ## Protected Endpoints (auth required)
 
@@ -41,16 +41,16 @@ Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
 | `POST /compile` | `{userid, project, name, source, primary_format?, secondary_format?}` | `{instructions, bytes}` |
 | `POST /run` | `{userid, project, name, primary_file?, record?, async?, nophi?}` | `{output, registers}` or `{job_id}` |
 | `POST /run/status` | `{userid, project, job_id}` | `{status: "running"/"done", output?}` |
-| `POST /publish` | `{userid, project, name, primary_file?, record?}` | `{report_url}` |
+| `POST /publish` | `{userid, project, name, primary_file?, record?, acl?}` | `{report_url}`. ACL: `public` (default), `authenticated`, `owner`, `token` |
 | `POST /unpublish` | `{userid, project, name}` | `{status: "ok"}` |
 | `POST /export-report` | `{userid, project, name, primary_file?, format?, title?, nophi?}` | `{output, files_written}` |
 
 ### Query & Data Operations
 | Endpoint | Body | Response |
 |----------|------|----------|
-| `POST /query` | `{userid, project, file, where?, select?, aggregate?, order_by?, limit?, join?, pivot?, mercury?}` | `{records, total}` |
+| `POST /query` | `{userid, project, file, where?: [{field, op, value}], select?, aggregate?, order_by?, limit?, join?, pivot?, mercury?}` | `{records, total}` |
 | `POST /sort` | `{userid, project, file, sort_by}` | `{status: "ok"}` |
-| `POST /index` | `{userid, project, file, field}` | `{status: "ok"}` |
+| `POST /index` | `{userid, project, file, key_fields: ["field1", "field2"], output: "INDEXNAME"}` | `{status: "ok"}` |
 | `POST /merge` | `{userid, project, file_a, file_b, output, key}` | `{status: "ok"}` |
 
 ### Optimization (HULDRA)
@@ -82,6 +82,6 @@ Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
 ## Key Rules
 
 - `userid` in every request body must match the authenticated user (403 if not)
-- API keys never expire. Login generates a new key and invalidates the old one
-- Data endpoints require a signed BAA (403 if unsigned)
-- All `.DA` files expire after 90 days by default
+- API keys expire after 90 days. Login generates a new key (old keys remain valid until expiration)
+- BAA only required for PHI data. Non-PHI data works without signing a BAA
+- All `.DA` files expire after 90 days by default. Set `expires_in_days` on import to override (up to 36500 days)

package/references/gotchas.md

@@ -52,8 +52,8 @@ Every request body's `userid` must equal your username. 403 on mismatch.
 ### Login invalidates the old key
 `POST /login` generates a new API key. The old one is dead. Save the new one immediately.
 
-### BAA required for data operations
-All import/export/compile/run/query/email endpoints return 403 without a signed BAA. Check with `/baa-status` first.
+### 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.
 
 ### 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"`.
@@ -109,3 +109,32 @@ All outbound emails are AI-screened. Blocked emails return 403.
 
 ### PHI in email
 Emails containing PHI identifiers (names, SSNs, dates of birth, etc.) are blocked by the content moderator.
+
+## Concurrency Model
+
+### Last-write-wins is intentional, not a missing feature
+
+Chaprola uses **last-write-wins** instead of ACID transactions. This is a deliberate architectural choice, not a gap.
+
+**Why last-write-wins is often the right model:**
+
+ACID transactions solve one problem: what happens when two writers hit the same record simultaneously? Record locking, deadlock detection, lock wait queues, transaction logs, and rollback mechanisms all exist to answer that question.
+
+For most real-world data, the answer is: they don't. Application data is typically **partitioned by owner** — a user's settings, a user's records, a user's event history. One writer per partition. No contention. In these workloads, transaction machinery is pure overhead solving a problem that doesn't exist.
+
+Last-write-wins eliminates that overhead entirely. No lock acquisition. No lock wait. No deadlock detection. Every write goes straight through.
+
+**What Chaprola does provide:**
+
+- **Single-object atomicity**: Each S3 `put_object` either completes or fails — no partial writes within a single data file.
+- **Consolidation dirty-bit checks**: The `/consolidate` endpoint verifies the merge file wasn't modified during the operation. If it was, consolidation aborts.
+- **11-nines durability**: S3's 99.999999999% durability guarantee means your data survives once written.
+
+**What Chaprola does not provide:**
+
+- **Multi-object atomicity**: If you need "write record A and record B or neither," keep that logic in a relational database. Chaprola writes each object independently.
+- **Read-modify-write isolation**: Two agents reading the same record, modifying it, and writing back will result in last-write-wins. If you need compare-and-swap semantics, Chaprola is not the right tool for that specific operation.
+
+**When to use a relational database instead:**
+
+When multiple concurrent writers update the same record — financial ledgers, inventory counters, auction bidding. If your application has true multi-writer contention on shared records, use PostgreSQL or similar for that workload. But most application data is owner-partitioned, and for that, last-write-wins is the lighter, faster, correct choice.