@chaprola/mcp-server 1.6.3 → 1.6.4

package/dist/index.js

@@ -102,7 +102,7 @@ const server = new McpServer({
 - **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)
+- **Schema:** chaprola_format (inspect fields), chaprola_alter (add/widen/rename/drop fields — NON-DESTRUCTIVE. Use this, NOT chaprola_import, to modify schemas on existing data.)
 - **Export:** chaprola_export (JSON or FHIR — full round-trip: FHIR in, process, FHIR out)
 - **Schedule:** chaprola_schedule (cron jobs for any endpoint)
 
@@ -174,6 +174,9 @@ server.resource("ref-import", "chaprola://ref/import", { description: "Import, e
 server.resource("ref-query", "chaprola://ref/query", { description: "Query, sort, index, merge, record CRUD — data operations", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/query", mimeType: "text/markdown", text: readRef("ref-query.md") }],
 }));
+server.resource("ref-schema", "chaprola://ref/schema", { description: "Schema operations — /format (inspect), /alter (widen/rename/add/drop fields). CRITICAL: Use /alter for schema changes, NOT /import.", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/schema", mimeType: "text/markdown", text: readRef("ref-schema.md") }],
+}));
 server.resource("ref-pivot", "chaprola://ref/pivot", { description: "Pivot tables (GROUP BY) — row, column, aggregate functions", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/pivot", mimeType: "text/markdown", text: readRef("ref-pivot.md") }],
 }));
@@ -277,8 +280,9 @@ server.tool("chaprola_report", "Run a published program and return output. No au
     project: z.string().describe("Project containing the program"),
     name: z.string().describe("Name of the published .PR file"),
     token: z.string().optional().describe("Action token (act_...) for writable reports. Required to persist WRITE/DELETE/QUERY operations. Provided when program was published with writable=true."),
-    params: z.record(z.union([z.string(), z.number()])).optional().describe("Parameters to inject before execution. Named params (e.g., {deck: \"kanji\", level: 3}) are read in programs via PARAM.name. Legacy R-variables (r1-r20) also supported. Use chaprola_report_params to discover what params a report accepts."),
-}, async ({ userid, project, name, token, params }) => {
+    params: z.string().optional().describe("JSON object of named params, e.g. {\"deck\": \"kanji\", \"level\": 3}. Named params are read in programs via PARAM.name. Legacy R-variables (r1-r20) also supported. Use chaprola_report_params to discover what params a report accepts."),
+}, async ({ userid, project, name, token, params: paramsStr }) => {
+    const params = typeof paramsStr === 'string' ? JSON.parse(paramsStr) : paramsStr;
     const urlParams = new URLSearchParams();
     urlParams.set("userid", userid);
     urlParams.set("project", project);
@@ -330,13 +334,14 @@ server.tool("chaprola_baa_status", "Check whether the authenticated user has sig
     return textResult(res);
 });
 // --- Import ---
-server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). Sign BAA first if handling PHI", {
+server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). DESTRUCTIVE: This REPLACES both the format (.F) and data (.DA) files if they already exist. All existing data will be lost. Use chaprola_alter to modify field widths/schema on existing data. Use chaprola_import only for new data or when replacing entire datasets. Sign BAA first if handling PHI", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
-    data: z.array(z.record(z.any())).describe("Array of flat JSON objects to import"),
+    data: z.string().describe("JSON array of record objects to import"),
     format: z.enum(["json", "fhir"]).optional().describe("Data format: json (default) or fhir"),
     expires_in_days: z.number().optional().describe("Days until data expires (default: 90)"),
-}, async ({ project, name, data, format, expires_in_days }) => withBaaCheck(async () => {
+}, async ({ project, name, data: dataStr, format, expires_in_days }) => withBaaCheck(async () => {
+    const data = typeof dataStr === 'string' ? JSON.parse(dataStr) : dataStr;
     const { username } = getCredentials();
     const body = { userid: username, project, name, data };
     if (format)
@@ -346,7 +351,7 @@ server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F
     const res = await authedFetch("/import", body);
     return textResult(res);
 }));
-server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large files (bypasses 6MB API Gateway limit)", {
+server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large files (bypasses 6MB API Gateway limit). DESTRUCTIVE: The subsequent chaprola_import_process will replace existing data. Use chaprola_alter to modify schemas on existing data.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
 }, async ({ project, name }) => withBaaCheck(async () => {
@@ -354,7 +359,7 @@ server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large file
     const res = await authedFetch("/import-url", { userid: username, project, name });
     return textResult(res);
 }));
-server.tool("chaprola_import_process", "Process a file previously uploaded to S3 via presigned URL. Generates .F + .DA files", {
+server.tool("chaprola_import_process", "Process a file previously uploaded to S3 via presigned URL. Generates .F + .DA files. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
     format: z.enum(["json", "fhir"]).optional().describe("Data format: json (default) or fhir"),
@@ -366,10 +371,10 @@ server.tool("chaprola_import_process", "Process a file previously uploaded to S3
     const res = await authedFetch("/import-process", body);
     return textResult(res);
 }));
-server.tool("chaprola_import_download", "Import data directly from a public URL (CSV, TSV, JSON, NDJSON, Parquet, Excel). Optional AI-powered schema inference", {
+server.tool("chaprola_import_download", "Import data directly from a public URL (CSV, TSV, JSON, NDJSON, Parquet, Excel). Optional AI-powered schema inference. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Output file name (without extension)"),
-    url: z.string().url().describe("Public URL to download (http/https only)"),
+    url: z.string().describe("Public URL to download (http/https only)"),
     instructions: z.string().optional().describe("Natural language instructions for AI-powered field selection and transforms"),
     max_rows: z.number().optional().describe("Maximum rows to import (default: 5,000,000)"),
 }, async ({ project, name, url, instructions, max_rows }) => withBaaCheck(async () => {
@@ -539,16 +544,22 @@ server.tool("chaprola_download", "Get a presigned S3 URL to download any file yo
 server.tool("chaprola_query", "SQL-free data query with WHERE, SELECT, aggregation, ORDER BY, JOIN, pivot, and Mercury scoring", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file to query"),
-    where: z.record(z.any()).optional().describe("Filter: {field, op, value}. Ops: eq, ne, gt, ge, lt, le, between, contains, starts_with"),
+    where: z.string().optional().describe("JSON object of filter conditions, e.g. {\"field\": \"status\", \"op\": \"eq\", \"value\": \"active\"}. Ops: eq, ne, gt, ge, lt, le, between, contains, starts_with"),
     select: z.array(z.string()).optional().describe("Fields to include in output"),
-    aggregate: z.array(z.record(z.any())).optional().describe("Aggregation: [{field, func}]. Funcs: count, sum, avg, min, max, stddev"),
-    order_by: z.array(z.record(z.any())).optional().describe("Sort: [{field, dir}]"),
+    aggregate: z.string().optional().describe("JSON array of aggregation specs, e.g. [{\"field\": \"amount\", \"func\": \"sum\"}]. Funcs: count, sum, avg, min, max, stddev"),
+    order_by: z.string().optional().describe("JSON array of sort specs, e.g. [{\"field\": \"name\", \"dir\": \"asc\"}]"),
     limit: z.number().optional().describe("Max results to return"),
     offset: z.number().optional().describe("Skip this many results"),
-    join: z.record(z.any()).optional().describe("Join: {file, on, type, method}"),
-    pivot: z.record(z.any()).optional().describe("Pivot: {row, column, values, totals, grand_total}"),
-    mercury: z.record(z.any()).optional().describe("Mercury scoring: {fields: [{field, target, weight}]}"),
-}, async ({ project, file, where, select, aggregate, order_by, limit, offset, join, pivot, mercury }) => withBaaCheck(async () => {
+    join: z.string().optional().describe("JSON object of join config, e.g. {\"file\": \"other\", \"on\": \"id\", \"type\": \"inner\"}"),
+    pivot: z.string().optional().describe("JSON object of pivot config, e.g. {\"row\": \"category\", \"column\": \"month\", \"values\": \"sales\"}"),
+    mercury: z.string().optional().describe("JSON object of mercury scoring config, e.g. {\"fields\": [{\"field\": \"score\", \"target\": 100, \"weight\": 1.0}]}"),
+}, async ({ project, file, where: whereStr, select, aggregate: aggregateStr, order_by: orderByStr, limit, offset, join: joinStr, pivot: pivotStr, mercury: mercuryStr }) => withBaaCheck(async () => {
+    const where = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
+    const aggregate = typeof aggregateStr === 'string' ? JSON.parse(aggregateStr) : aggregateStr;
+    const order_by = typeof orderByStr === 'string' ? JSON.parse(orderByStr) : orderByStr;
+    const join = typeof joinStr === 'string' ? JSON.parse(joinStr) : joinStr;
+    const pivot = typeof pivotStr === 'string' ? JSON.parse(pivotStr) : pivotStr;
+    const mercury = typeof mercuryStr === 'string' ? JSON.parse(mercuryStr) : mercuryStr;
     const { username } = getCredentials();
     const body = { userid: username, project, file };
     if (where)
@@ -617,7 +628,7 @@ server.tool("chaprola_format", "Inspect a data file's schema — returns field n
     const res = await authedFetch("/format", { userid: username, project, name });
     return textResult(res);
 }));
-server.tool("chaprola_alter", "Modify a data file's schema: widen/narrow/rename fields, add new fields, drop fields. Transforms existing data to match the new schema.", {
+server.tool("chaprola_alter", "Modify a data file's schema: widen/narrow/rename fields, add new fields, drop fields. NON-DESTRUCTIVE: Transforms existing data to match the new schema. This is the ONLY safe way to change field widths or schema on existing data files. Unlike chaprola_import which replaces all data, chaprola_alter preserves and reformats existing records.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Data file name (without extension)"),
     alter: z.array(z.object({
@@ -756,7 +767,7 @@ server.tool("chaprola_search", "Search the web via Brave Search API. Returns tit
 }));
 // --- Fetch ---
 server.tool("chaprola_fetch", "Fetch any URL and return clean content. HTML pages converted to markdown. SSRF-protected. Rate limit: 20/day per user", {
-    url: z.string().url().describe("URL to fetch (http:// or https://)"),
+    url: z.string().describe("URL to fetch (http:// or https://)"),
     format: z.enum(["markdown", "text", "html", "json"]).optional().describe("Output format (default: markdown)"),
     max_length: z.number().optional().describe("Max output characters (default: 50000, max: 200000)"),
 }, async ({ url, format, max_length }) => withBaaCheck(async () => {
@@ -773,9 +784,10 @@ server.tool("chaprola_schedule", "Create a scheduled job that runs a Chaprola en
     name: z.string().describe("Unique name for this schedule (alphanumeric + hyphens/underscores)"),
     cron: z.string().describe("Standard 5-field cron expression (min hour day month weekday). Minimum interval: 15 minutes"),
     endpoint: z.enum(["/import-download", "/run", "/export-report", "/search", "/fetch", "/query", "/email/send", "/export", "/report", "/list"]).describe("Target endpoint to call"),
-    body: z.record(z.any()).describe("Request body for the target endpoint. userid is injected automatically"),
+    body: z.string().describe("JSON object of the schedule request body. userid is injected automatically"),
     skip_if_unchanged: z.boolean().optional().describe("Skip when response matches previous run (SHA-256 hash). Default: false"),
-}, async ({ name, cron, endpoint, body, skip_if_unchanged }) => withBaaCheck(async () => {
+}, async ({ name, cron, endpoint, body: bodyStr, skip_if_unchanged }) => withBaaCheck(async () => {
+    const body = typeof bodyStr === 'string' ? JSON.parse(bodyStr) : bodyStr;
     const reqBody = { name, cron, endpoint, body };
     if (skip_if_unchanged !== undefined)
         reqBody.skip_if_unchanged = skip_if_unchanged;
@@ -796,8 +808,9 @@ server.tool("chaprola_schedule_delete", "Delete a scheduled job by name", {
 server.tool("chaprola_insert_record", "Insert a new record into a data file's merge file (.MRG). The record appears at the end of the file until consolidation.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-    record: z.record(z.string()).describe("Field name → value pairs. Unspecified fields default to blanks."),
-}, async ({ project, file, record }) => withBaaCheck(async () => {
+    record: z.string().describe("JSON object of the record to insert, e.g. {\"name\": \"foo\", \"status\": \"active\"}. Unspecified fields default to blanks."),
+}, async ({ project, file, record: recordStr }) => withBaaCheck(async () => {
+    const record = typeof recordStr === 'string' ? JSON.parse(recordStr) : recordStr;
     const { username } = getCredentials();
     const res = await authedFetch("/insert-record", { userid: username, project, file, record });
     return textResult(res);
@@ -805,9 +818,11 @@ server.tool("chaprola_insert_record", "Insert a new record into a data file's me
 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)"),
-    where: z.record(z.string()).describe("Field name → value pairs to identify exactly one record"),
-    set: z.record(z.string()).describe("Field name → new value pairs to update"),
-}, async ({ project, file, where: whereClause, set }) => withBaaCheck(async () => {
+    where: z.string().describe("JSON object of filter conditions for which records to update, e.g. {\"id\": \"123\"}"),
+    set: z.string().describe("JSON object of fields to update, e.g. {\"status\": \"done\"}"),
+}, async ({ project, file, where: whereStr, set: setStr }) => withBaaCheck(async () => {
+    const whereClause = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
+    const set = typeof setStr === 'string' ? JSON.parse(setStr) : setStr;
     const { username } = getCredentials();
     const res = await authedFetch("/update-record", { userid: username, project, file, where: whereClause, set });
     return textResult(res);
@@ -815,8 +830,9 @@ server.tool("chaprola_update_record", "Update fields in a single record matched
 server.tool("chaprola_delete_record", "Delete a single record matched by a where clause. Marks the record as ignored (.IGN). Physically removed on consolidation.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-    where: z.record(z.string()).describe("Field name → value pairs to identify exactly one record"),
-}, async ({ project, file, where: whereClause }) => withBaaCheck(async () => {
+    where: z.string().describe("JSON object of filter conditions for which records to delete, e.g. {\"id\": \"123\"}"),
+}, async ({ project, file, where: whereStr }) => withBaaCheck(async () => {
+    const whereClause = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
     const { username } = getCredentials();
     const res = await authedFetch("/delete-record", { userid: username, project, file, where: whereClause });
     return textResult(res);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.6.3",
-  "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.",
+  "version": "1.6.4",
+  "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents 47 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",
   "bin": {

package/references/ref-gotchas.md

@@ -11,6 +11,7 @@
 - **Statement numbers are labels, not line numbers.** Only number GOTO/CALL targets.
 
 ## API
+- **NEVER use `/import` to change field widths.** `/import` REPLACES existing data. Use `/alter` to widen/narrow fields while preserving data. See `chaprola://ref/schema`.
 - **userid must match authenticated user.** 403 on mismatch.
 - **Login invalidates the old key.** Save the new one immediately.
 - **Async for large datasets.** `/run` with `async: true` for >100K records (API Gateway 30s timeout).

package/references/ref-import.md

@@ -10,6 +10,14 @@ POST /import {userid, project, name: "STAFF", data: [{"name": "Alice", "salary":
 
 Field widths auto-sized from longest value. Default expiry: 90 days. Override with `expires_in_days`.
 
+### ⚠️ DESTRUCTIVE WARNING
+
+**`/import` REPLACES both the format (.F) and data (.DA) files if they already exist. All existing data will be lost.**
+
+- **Use `/import` ONLY for:** Creating brand new data files or intentionally replacing entire datasets
+- **DO NOT use `/import` to:** Change field widths or modify schema on existing data
+- **Use `/alter` instead** to modify field widths/schema while preserving existing data (see `chaprola://ref/schema`)
+
 ## Large File Upload (presigned URL)
 ```bash
 POST /import-url {userid, project, name} → {upload_url, staging_key}
@@ -17,11 +25,15 @@ POST /import-url {userid, project, name} → {upload_url, staging_key}
 POST /import-process {userid, project, name, staging_key} → same as /import
 ```
 
+**WARNING:** `/import-process` is also DESTRUCTIVE and replaces existing data. Use `/alter` for schema changes.
+
 ## POST /import-download
 `{userid, project, name, url, instructions?, max_rows?}`
 Imports directly from URL. Supports: CSV, TSV, JSON, NDJSON, Parquet, Excel (.xlsx/.xls).
 Optional `instructions` for AI schema inference. Max 1M records.
 
+**WARNING:** `/import-download` is also DESTRUCTIVE and replaces existing data. Use `/alter` for schema changes.
+
 ## POST /export
 `{userid, project, name, format?}` → `{data: [...records]}`
 Optional `format: "fhir"` for FHIR JSON reconstruction.

package/references/ref-schema.md

@@ -0,0 +1,166 @@
+# Schema Inspection & Modification
+
+## POST /format
+Inspect a data file's schema — returns field names, positions, lengths, types, and PHI flags.
+
+```bash
+POST /format {userid, project, name: "STAFF"}
+```
+
+Returns:
+```json
+{
+  "format_file": "s3://chaprola-2026/userid/project/format/STAFF.F",
+  "fields": [
+    {"name": "name", "position": 1, "length": 50, "type": "text", "phi": false},
+    {"name": "salary", "position": 51, "length": 10, "type": "numeric", "phi": false}
+  ],
+  "record_length": 60
+}
+```
+
+Use this to inspect the current schema before making changes with `/alter`.
+
+---
+
+## POST /alter
+**NON-DESTRUCTIVE schema modification.** Modifies field widths, renames fields, adds new fields, or drops fields. Existing data is preserved and reformatted to match the new schema.
+
+### ⚠️ CRITICAL: Use /alter for schema changes, NOT /import
+
+**DO NOT use `/import` to change field widths or schema on existing data files.** `/import` REPLACES both the format (.F) and data (.DA) files, destroying all existing data.
+
+**Use `/alter` when you need to:**
+- Widen or narrow field widths
+- Rename fields
+- Add new fields to existing data
+- Drop unused fields
+- Change field types
+
+**Use `/import` only when:**
+- Creating a brand new data file
+- Intentionally replacing an entire dataset
+
+---
+
+## /alter Request Format
+
+```json
+{
+  "userid": "...",
+  "project": "...",
+  "name": "STAFF",
+  "alter": [
+    {"field": "name", "width": 100},        // widen from 50 to 100
+    {"field": "dept", "rename": "department"}
+  ],
+  "add": [
+    {"name": "email", "width": 80, "type": "text", "after": "name"}
+  ],
+  "drop": ["old_field"],
+  "output": "STAFF_V2"  // optional: create new file instead of in-place
+}
+```
+
+### Parameters
+
+**`alter`** (optional): Array of field modifications
+- `field` (required): Field name to modify
+- `width` (optional): New width (can widen or narrow)
+- `rename` (optional): New field name
+- `type` (optional): Change type (`"text"` or `"numeric"`)
+
+**`add`** (optional): Array of new fields to add
+- `name` (required): New field name
+- `width` (required): Field width
+- `type` (optional): `"text"` (default) or `"numeric"`
+- `after` (optional): Insert after this field (default: end of record)
+
+**`drop`** (optional): Array of field names to remove
+
+**`output`** (optional): Output file name. If not specified, modifies in-place.
+
+---
+
+## Examples
+
+### Widen a field (most common case)
+```bash
+# Widen 'description' field from 100 to 500 characters
+POST /alter {
+  userid, project, name: "ITEMS",
+  alter: [{"field": "description", "width": 500}]
+}
+```
+
+### Add a new field
+```bash
+# Add 'created_at' field after 'id'
+POST /alter {
+  userid, project, name: "RECORDS",
+  add: [{"name": "created_at", "width": 24, "after": "id"}]
+}
+```
+
+### Rename and widen
+```bash
+# Rename 'dept' to 'department' and widen to 50
+POST /alter {
+  userid, project, name: "STAFF",
+  alter: [{"field": "dept", "rename": "department", "width": 50}]
+}
+```
+
+### Complex schema change
+```bash
+# Multiple operations in one call
+POST /alter {
+  userid, project, name: "EMPLOYEES",
+  alter: [
+    {"field": "name", "width": 100},
+    {"field": "dept_id", "rename": "department_id"}
+  ],
+  add: [
+    {"name": "email", "width": 80, "after": "name"},
+    {"name": "hire_date", "width": 10, "type": "text"}
+  ],
+  drop: ["legacy_field", "unused_column"]
+}
+```
+
+---
+
+## How /alter Works Internally
+
+1. **Reads the old format (.F)** to understand current field positions
+2. **Creates a new format (.F)** with your requested changes
+3. **Reads all records from the old data (.DA)**
+4. **Reformats each record** to match the new schema:
+   - Widened fields: existing data left-aligned, space-padded
+   - Narrowed fields: truncated to new width
+   - New fields: filled with spaces
+   - Dropped fields: removed from record
+5. **Writes reformatted records** to the new data file
+6. **Replaces the old files** (if in-place) or creates new files (if `output` specified)
+
+This is a **safe, non-destructive transformation** of existing data. No data is lost unless you explicitly narrow fields or drop them.
+
+---
+
+## Common Gotchas
+
+1. **Narrowing fields truncates data** — if you narrow a field from 100 to 50, any values longer than 50 characters will be truncated. Use `/format` first to check max field lengths.
+
+2. **Field order matters for `after`** — when adding multiple fields, they're processed in order. If you add field B after field A, and also add field C after field A, field B will come first (because it was added first).
+
+3. **Cannot rename and drop the same field** — if you rename a field, don't also include it in the `drop` array.
+
+4. **Output file must not exist** — if you specify an `output` name and that file already exists, the operation will fail.
+
+---
+
+## See Also
+
+- `/format` — inspect current schema before making changes
+- `/import` — create NEW data files (DESTRUCTIVE if file exists)
+- `/query` — query data after schema changes