@chaprola/mcp-server 1.7.0 → 1.9.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.
@@ -103,6 +103,7 @@ const server = new McpServer({
 - **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 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)
 
@@ -395,33 +396,50 @@ 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, 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.", {
+server.tool("chaprola_compile", `Compile Chaprola source (.CS) to bytecode (.PR). READ chaprola://cookbook BEFORE writing source.
+
+STYLE RULES (mandatory — project review enforces these):
+1. Use QUERY instead of SEEK loops for filtering or single-record lookup. SEEK loops only for processing every record unconditionally.
+2. Don't use MOVE + IF EQUAL for comparisons — use QUERY WHERE.
+3. Use implicit variable assignment (LET name = value) — don't use DEFINE VARIABLE.
+4. END/STOP only for early exit — not needed at end of program.
+5. OPEN PRIMARY not needed when using QUERY with primary_format.
+6. Use named read (READ name rec + name.field) instead of OPEN SECONDARY + S.field for QUERY results.
+7. Every program MUST have an intent file (.DS) — one paragraph: what the program does, parameters, output, who uses it.
+8. Add a comment header — first lines describe purpose and parameters.
+9. Use PRINT concatenation (PRINT "text" + P.field + R1), not MOVE + PRINT 0 buffers.
+10. Use RECORDNUMBERS for bulk delete: QUERY INTO name, then DELETE PRIMARY name.RECORDNUMBERS.
+
+KEY SYNTAX: no PROGRAM keyword (start with commands), no commas, LET supports one operation (no parentheses), no built-in functions. Use primary_format to enable P.fieldname addressing — 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 (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)"),
-}, async ({ project, name, source, primary_format, secondary_format }) => 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, 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)
@@ -438,9 +456,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)
@@ -457,9 +476,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.", {
@@ -472,9 +492,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)
@@ -532,9 +553,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)
@@ -553,9 +575,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 ---
@@ -571,7 +594,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;
@@ -579,7 +603,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)
@@ -610,9 +634,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 ---
@@ -620,9 +645,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 ---
@@ -632,9 +658,10 @@ 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 ---
@@ -677,6 +704,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"),
@@ -827,10 +872,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.", {
@@ -838,38 +884,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,6 +1,6 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.7.0",
+  "version": "1.9.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",