@chaprola/mcp-server 1.6.4 → 1.8.0

package/dist/index.js

@@ -84,7 +84,7 @@ async function withBaaCheck(fn) {
 // --- Server setup ---
 const server = new McpServer({
     name: "chaprola",
-    version: "1.4.1",
+    version: "1.8.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.
@@ -102,11 +102,12 @@ 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 — NON-DESTRUCTIVE. Use this, NOT chaprola_import, to modify schemas on existing data.)
+- **Schema:** chaprola_format (inspect fields), chaprola_alter (add/widen/rename/drop fields — NON-DESTRUCTIVE for in-place schema edits). Re-imports now preserve and widen existing schemas automatically when targeting an existing file.
+- **Intent:** chaprola_intent (read/write/delete project and program descriptions — helps maintenance coders understand purpose)
 - **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). Named parameters: PARAM.name reads URL query params as strings; LET x = PARAM.name converts to numeric. Named output positions: U.name instead of U1-U20.
+**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, reports can use either the classic MOVE-to-U-buffer then PRINT 0 pattern or one-line PRINT concatenation, and LET supports one operation (no parentheses). Named parameters: PARAM.name reads URL query params as strings; LET x = PARAM.name converts to numeric. Named output positions: U.name instead of U1-U20.
 
 **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.
@@ -155,7 +156,7 @@ function readRef(filename) {
 server.resource("cookbook", "chaprola://cookbook", { description: "Chaprola language cookbook — syntax patterns, complete examples, and the import→compile→run workflow. READ THIS before writing any Chaprola source code.", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://cookbook", mimeType: "text/markdown", text: readRef("cookbook.md") }],
 }));
-server.resource("gotchas", "chaprola://gotchas", { description: "Common Chaprola mistakes — no parentheses in LET, no commas in PRINT, MOVE length must match field width, DEFINE names must not collide with fields. READ THIS before writing code.", mimeType: "text/markdown" }, async () => ({
+server.resource("gotchas", "chaprola://gotchas", { description: "Common Chaprola mistakes — no parentheses in LET, no commas in PRINT, DEFINE names must not collide with fields, always pass primary_format to compile. READ THIS before writing code.", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://gotchas", mimeType: "text/markdown", text: readRef("gotchas.md") }],
 }));
 server.resource("endpoints", "chaprola://endpoints", { description: "Chaprola API endpoint reference — all 40 endpoints with request/response shapes", mimeType: "text/markdown" }, async () => ({
@@ -198,9 +199,12 @@ server.resource("ref-email", "chaprola://ref/email", { description: "Email syste
 server.resource("ref-gotchas", "chaprola://ref/gotchas", { description: "Common Chaprola mistakes — language, API, and secondary file pitfalls", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/gotchas", mimeType: "text/markdown", text: readRef("ref-gotchas.md") }],
 }));
-server.resource("ref-auth", "chaprola://ref/auth", { description: "Authentication details — registration, login, BAA, MCP env vars", mimeType: "text/markdown" }, async () => ({
+server.resource("ref-auth", "chaprola://ref/auth", { description: "Authentication details — registration, login, BAA, cross-user sharing, MCP env vars", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/auth", mimeType: "text/markdown", text: readRef("ref-auth.md") }],
 }));
+server.resource("ref-apps", "chaprola://ref/apps", { description: "Building apps on Chaprola — React/frontend architecture, site keys, single-owner vs multi-user, enterprise proxy pattern", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/apps", mimeType: "text/markdown", text: readRef("ref-apps.md") }],
+}));
 // --- MCP Prompts ---
 server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read this before writing any Chaprola source code.", async () => ({
     messages: [{
@@ -213,7 +217,7 @@ server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read
                     "- NO `PROGRAM` keyword — programs start directly with commands\n" +
                     "- NO commas anywhere — all arguments are space-separated\n" +
                     "- NO parentheses in LET — only `LET var = a OP b` (one operation)\n" +
-                    "- Output uses MOVE + PRINT 0 buffer model, NOT `PRINT field`\n" +
+                    "- Output can use classic MOVE + PRINT 0 buffers or one-line PRINT concatenation (`PRINT \"label\" + P.field + rec`)\n" +
                     "- Field addressing: P.fieldname (primary), S.fieldname (secondary)\n" +
                     "- Loop pattern: `LET rec = 1` → `SEEK rec` → `IF EOF GOTO end` → process → `LET rec = rec + 1` → `GOTO loop`\n\n" +
                     "## Minimal Example\n" +
@@ -222,10 +226,7 @@ server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read
                     "LET rec = 1\n" +
                     "100 SEEK rec\n" +
                     "    IF EOF GOTO 900\n" +
-                    "    MOVE BLANKS U.1 40\n" +
-                    "    MOVE P.name U.1 8\n" +
-                    "    MOVE P.value U.12 6\n" +
-                    "    PRINT 0\n" +
+                    "    PRINT P.name + \" — \" + P.value\n" +
                     "    LET rec = rec + 1\n" +
                     "    GOTO 100\n" +
                     "900 END\n" +
@@ -246,6 +247,10 @@ server.tool("chaprola_hello", "Health check — verify the Chaprola API is runni
     const res = await fetch(url);
     return textResult(res);
 });
+server.tool("chaprola_help", "Get the full Chaprola documentation bundle from POST /help. Call this before guessing when compile or run fails. No auth required.", {}, async () => {
+    const res = await publicFetch("POST", "/help", {});
+    return textResult(res);
+});
 server.tool("chaprola_register", "Register a new Chaprola account. Returns an API key — save it immediately", {
     username: z.string().describe("3-40 chars, alphanumeric + hyphens/underscores, starts with letter"),
     passcode: z.string().describe("16-128 characters. Use a long, unique passcode"),
@@ -334,7 +339,7 @@ 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). 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", {
+server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). If the target file already exists, Chaprola preserves the existing schema, widens matching fields as needed, keeps legacy fields as blanks, and appends new fields at the end. Use chaprola_alter for explicit in-place schema surgery. Sign BAA first if handling PHI", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
     data: z.string().describe("JSON array of record objects to import"),
@@ -351,7 +356,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). DESTRUCTIVE: The subsequent chaprola_import_process will replace existing data. Use chaprola_alter to modify schemas on existing data.", {
+server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large files (bypasses 6MB API Gateway limit). The subsequent chaprola_import_process preserves and widens an existing schema automatically when importing into an existing file.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
 }, async ({ project, name }) => withBaaCheck(async () => {
@@ -359,7 +364,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. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
+server.tool("chaprola_import_process", "Process a file previously uploaded to S3 via presigned URL. Generates .F + .DA files. If the target file already exists, the existing schema is preserved and widened automatically as needed.", {
     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"),
@@ -371,7 +376,7 @@ 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. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
+server.tool("chaprola_import_download", "Import data directly from a public URL (CSV, TSV, JSON, NDJSON, Parquet, Excel). Optional AI-powered schema inference.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Output file name (without extension)"),
     url: z.string().describe("Public URL to download (http/https only)"),
@@ -391,33 +396,36 @@ server.tool("chaprola_import_download", "Import data directly from a public URL
 server.tool("chaprola_export", "Export Chaprola .DA + .F files back to JSON", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
-}, async ({ project, name }) => withBaaCheck(async () => {
+    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, name, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/export", { userid: username, project, name });
+    const res = await authedFetch("/export", { userid: userid || username, project, name });
     return textResult(res);
 }));
 // --- List ---
 server.tool("chaprola_list", "List files in a project with optional wildcard pattern", {
     project: z.string().describe("Project name (use * for all projects)"),
     pattern: z.string().optional().describe("Wildcard pattern to filter files (e.g., EMP*)"),
-}, async ({ project, pattern }) => withBaaCheck(async () => {
+    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, pattern, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const body = { userid: username, project };
+    const body = { userid: userid || username, project };
     if (pattern)
         body.pattern = pattern;
     const res = await authedFetch("/list", body);
     return textResult(res);
 }));
 // --- Compile ---
-server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR). READ chaprola://cookbook BEFORE writing source. Key syntax: no PROGRAM keyword (start with commands), no commas, MOVE+PRINT 0 buffer model (not PRINT field), SEEK for primary records, OPEN/READ/WRITE/CLOSE for secondary files, LET supports one operation (no parentheses), field addressing via P.field/S.field requires primary_format/secondary_format params.", {
+server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR). READ chaprola://cookbook BEFORE writing source. Key syntax: no PROGRAM keyword (start with commands), no commas, reports can use MOVE+PRINT 0 buffers or one-line PRINT concatenation, SEEK for primary records, OPEN/READ/WRITE/CLOSE for secondary files, LET supports one operation (no parentheses). Use primary_format to enable P.fieldname addressing (recommended) — the compiler resolves field names to positions and lengths from the format file. If compile fails, call chaprola_help before retrying.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Program name (without extension)"),
     source: z.string().describe("Chaprola source code"),
-    primary_format: z.string().optional().describe("Primary data file name (enables P.fieldname addressing)"),
-    secondary_format: z.string().optional().describe("Secondary format file name (enables S.fieldname addressing)"),
-}, async ({ project, name, source, primary_format, secondary_format }) => withBaaCheck(async () => {
+    primary_format: z.string().optional().describe("Primary data file name — enables P.fieldname addressing (recommended for all programs that reference data fields)"),
+    secondary_format: z.string().optional().describe("Secondary data file name — enables S.fieldname addressing (required if using S.fieldname references)"),
+    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, name, source, primary_format, secondary_format, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const body = { userid: username, project, name, source };
+    const body = { userid: userid || username, project, name, source };
     if (primary_format)
         body.primary_format = primary_format;
     if (secondary_format)
@@ -426,7 +434,7 @@ server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR)
     return textResult(res);
 }));
 // --- Run ---
-server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for large datasets (>100K records)", {
+server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for large datasets (>100K records). If runtime errors occur, call chaprola_help before retrying.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Program name (without extension)"),
     primary_file: z.string().optional().describe("Primary data file to load"),
@@ -434,9 +442,10 @@ server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for
     async_exec: z.boolean().optional().describe("If true, run asynchronously and return job_id for polling"),
     secondary_files: z.array(z.string()).optional().describe("Secondary files to make available"),
     nophi: z.boolean().optional().describe("If true, obfuscate PHI-flagged fields during execution"),
-}, async ({ project, name, primary_file, record, async_exec, secondary_files, nophi }) => withBaaCheck(async () => {
+    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, name, primary_file, record, async_exec, secondary_files, nophi, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const body = { userid: username, project, name };
+    const body = { userid: userid || username, project, name };
     if (primary_file)
         body.primary_file = primary_file;
     if (record !== undefined)
@@ -453,9 +462,10 @@ server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for
 server.tool("chaprola_run_status", "Check status of an async job. Returns full output when done", {
     project: z.string().describe("Project name"),
     job_id: z.string().describe("Job ID from async /run response"),
-}, async ({ project, job_id }) => withBaaCheck(async () => {
+    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, job_id, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/run/status", { userid: username, project, job_id });
+    const res = await authedFetch("/run/status", { userid: 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.", {
@@ -468,9 +478,10 @@ server.tool("chaprola_run_each", "Run a compiled .PR program against every recor
         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 () => {
+    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, program, where, where_logic, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const body = { userid: username, project, file, program };
+    const body = { userid: userid || username, project, file, program };
     if (where)
         body.where = where;
     if (where_logic)
@@ -478,6 +489,20 @@ server.tool("chaprola_run_each", "Run a compiled .PR program against every recor
     const res = await authedFetch("/run-each", body);
     return textResult(res);
 }));
+// --- Systemhelp ---
+server.tool("chaprola_systemhelp", "Send your program name and error message. Chaprola will read your source, intent file, and data schema to diagnose and fix the problem. See POST /help for examples.", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("Program name (without extension)"),
+    error: z.string().optional().describe("Error message from compile or runtime (copy verbatim if available)"),
+    request: z.string().describe("Plain-language description of the problem. Include context: what changed, what you expected, what happened instead."),
+}, async ({ project, name, error, request }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name, request };
+    if (error)
+        body.error = error;
+    const res = await authedFetch("/systemhelp", body);
+    return textResult(res);
+}));
 // --- Publish ---
 server.tool("chaprola_publish", "Publish a compiled program for public access via /report", {
     project: z.string().describe("Project name"),
@@ -514,9 +539,10 @@ server.tool("chaprola_export_report", "Run a .PR program and save output as a pe
     format: z.enum(["text", "pdf", "csv", "json", "xlsx"]).optional().describe("Output format (default: text)"),
     title: z.string().optional().describe("Report title (used in PDF header)"),
     nophi: z.boolean().optional().describe("If true, obfuscate PHI-flagged fields"),
-}, async ({ project, name, primary_file, report_name, format, title, nophi }) => withBaaCheck(async () => {
+    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, name, primary_file, report_name, format, title, nophi, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const body = { userid: username, project, name };
+    const body = { userid: userid || username, project, name };
     if (primary_file)
         body.primary_file = primary_file;
     if (report_name)
@@ -535,9 +561,10 @@ server.tool("chaprola_download", "Get a presigned S3 URL to download any file yo
     project: z.string().describe("Project name"),
     file: z.string().describe("File name with extension (e.g., REPORT.R)"),
     type: z.enum(["data", "format", "source", "proc", "output"]).describe("File type directory"),
-}, async ({ project, file, type }) => withBaaCheck(async () => {
+    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, type, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/download", { userid: username, project, file, type });
+    const res = await authedFetch("/download", { userid: userid || username, project, file, type });
     return textResult(res);
 }));
 // --- Query ---
@@ -553,7 +580,8 @@ server.tool("chaprola_query", "SQL-free data query with WHERE, SELECT, aggregati
     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 () => {
+    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, where: whereStr, select, aggregate: aggregateStr, order_by: orderByStr, limit, offset, join: joinStr, pivot: pivotStr, mercury: mercuryStr, userid }) => 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;
@@ -561,7 +589,7 @@ server.tool("chaprola_query", "SQL-free data query with WHERE, SELECT, aggregati
     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 };
+    const body = { userid: userid || username, project, file };
     if (where)
         body.where = where;
     if (select)
@@ -592,9 +620,10 @@ server.tool("chaprola_sort", "Sort a data file by one or more fields. Modifies t
         dir: z.enum(["asc", "desc"]).optional(),
         type: z.enum(["text", "numeric"]).optional(),
     })).describe("Sort specification: [{field, dir?, type?}]"),
-}, async ({ project, file, sort_by }) => withBaaCheck(async () => {
+    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, sort_by, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/sort", { userid: username, project, file, sort_by });
+    const res = await authedFetch("/sort", { userid: userid || username, project, file, sort_by });
     return textResult(res);
 }));
 // --- Index ---
@@ -602,9 +631,10 @@ server.tool("chaprola_index", "Build an index file (.IDX) for fast lookups on a
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file to index"),
     field: z.string().describe("Field name to index"),
-}, async ({ project, file, field }) => withBaaCheck(async () => {
+    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, field, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/index", { userid: username, project, file, field });
+    const res = await authedFetch("/index", { userid: userid || username, project, file, field });
     return textResult(res);
 }));
 // --- Merge ---
@@ -614,13 +644,14 @@ server.tool("chaprola_merge", "Merge two sorted data files into one. Both must s
     file_b: z.string().describe("Second data file"),
     output: z.string().describe("Output file name"),
     key: z.string().describe("Merge key field"),
-}, async ({ project, file_a, file_b, output, key }) => withBaaCheck(async () => {
+    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_a, file_b, output, key, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/merge", { userid: username, project, file_a, file_b, output, key });
+    const res = await authedFetch("/merge", { userid: userid || username, project, file_a, file_b, output, key });
     return textResult(res);
 }));
 // --- Schema: Format + Alter ---
-server.tool("chaprola_format", "Inspect a data file's schema — returns field names, positions, lengths, types, and PHI flags", {
+server.tool("chaprola_format", "Inspect a data file's schema — returns field names, types, and PHI flags. Use this to understand the data structure before writing programs.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Data file name (without .F extension)"),
 }, async ({ project, name }) => withBaaCheck(async () => {
@@ -628,7 +659,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. 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.", {
+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. Use this for explicit schema surgery on existing data files; re-imports now preserve and widen existing schemas automatically, but chaprola_alter still handles rename/drop/narrow operations.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Data file name (without extension)"),
     alter: z.array(z.object({
@@ -659,6 +690,24 @@ server.tool("chaprola_alter", "Modify a data file's schema: widen/narrow/rename
     const res = await authedFetch("/alter", body);
     return textResult(res);
 }));
+// --- Intent ---
+server.tool("chaprola_intent", "Read, write, or delete project and program intent descriptions. Project intent describes the purpose of a project. Program intent (.DS file) describes what a specific program does. Omit 'text' and 'delete' to read. Provide 'text' to write. Set 'delete: true' to remove.", {
+    project: z.string().describe("Project name"),
+    name: z.string().optional().describe("Program name (without extension). Omit for project-level intent"),
+    text: z.string().optional().describe("Intent text to write. Omit to read current intent"),
+    delete: z.boolean().optional().describe("Set true to delete the intent"),
+}, async ({ project, name, text, delete: del }) => {
+    const { username } = getCredentials();
+    const body = { userid: username, project };
+    if (name)
+        body.name = name;
+    if (text !== undefined)
+        body.text = text;
+    if (del)
+        body.delete = true;
+    const res = await authedFetch("/intent", body);
+    return textResult(res);
+});
 // --- Optimize (HULDRA) ---
 server.tool("chaprola_optimize", "Run HULDRA nonlinear optimization using a compiled .PR as the objective evaluator", {
     project: z.string().describe("Project name"),
@@ -809,10 +858,11 @@ server.tool("chaprola_insert_record", "Insert a new record into a data file's me
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
     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 () => {
+    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, record: recordStr, userid }) => 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 });
+    const res = await authedFetch("/insert-record", { userid: userid || username, project, file, record });
     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.", {
@@ -820,38 +870,42 @@ server.tool("chaprola_update_record", "Update fields in a single record matched
     file: z.string().describe("Data file name (without extension)"),
     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 () => {
+    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, where: whereStr, set: setStr, userid }) => 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 });
+    const res = await authedFetch("/update-record", { userid: userid || username, project, file, where: whereClause, set });
     return textResult(res);
 }));
 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.string().describe("JSON object of filter conditions for which records to delete, e.g. {\"id\": \"123\"}"),
-}, async ({ project, file, where: whereStr }) => withBaaCheck(async () => {
+    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, where: whereStr, userid }) => 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 });
+    const res = await authedFetch("/delete-record", { userid: userid || username, project, file, where: whereClause });
     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)"),
-}, async ({ project, file }) => withBaaCheck(async () => {
+    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, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/consolidate", { userid: username, project, file });
+    const res = await authedFetch("/consolidate", { userid: userid || username, project, file });
     return textResult(res);
 }));
 // --- Challenge (Data Health) ---
 server.tool("chaprola_challenge", "Data health check: finds missing data, overdue dates, and incomplete records. Returns issues sorted by severity.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-}, async ({ project, file }) => withBaaCheck(async () => {
+    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, userid }) => withBaaCheck(async () => {
     const { username } = getCredentials();
-    const res = await authedFetch("/challenge", { userid: username, project, file });
+    const res = await authedFetch("/challenge", { userid: userid || username, project, file });
     return textResult(res);
 }));
 // --- Site Keys ---

package/package.json

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

package/references/auth.md

@@ -51,6 +51,39 @@ If you do handle PHI, sign the BAA once per account:
 
 These are read by the MCP server and injected into every authenticated request automatically.
 
+## Cross-User Project Sharing
+
+By default, only the project owner can read and write their data. To grant another user access, create an `access.json` file in the project root:
+
+```
+s3://chaprola-2026/{owner}/{project}/access.json
+```
+
+**Format:**
+```json
+{
+  "owner": "tawni",
+  "project": "social",
+  "discoverable": false,
+  "description": "Content calendar and social media",
+  "writers": [
+    {"username": "cal", "granted_at": "2026-04-06T17:25:16Z"},
+    {"username": "nora", "granted_at": "2026-04-06T17:25:16Z"}
+  ]
+}
+```
+
+**How it works:**
+- Any user in the `writers` list gets full read+write access to that project through all API endpoints (query, update-record, insert-record, delete-record, export, compile, run, run-each, etc.)
+- The shared user passes the **owner's** userid in requests: `{"userid": "tawni", "project": "social", ...}` — authenticated with their own API key
+- Every protected endpoint checks: (1) does the API key's username match the `userid`? If not, (2) is the user listed as a writer in `access.json`?
+- No `access.json` = no shared access (owner-only)
+- `discoverable` is reserved for future use (project discovery/listing)
+
+**To set up sharing:** Create or update the `access.json` file via S3 directly or through the `/sv` admin interface.
+
+**To revoke access:** Remove the user from the `writers` array, or delete `access.json` entirely.
+
 ## Credential Recovery
 
 If your API key stops working (403):