vtiger-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ViralP17
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# vtiger-mcp
+
+**MCP server + CLI for [vtiger CRM](https://www.vtiger.com/).** Connect any
+AI agent (Claude Desktop, Claude Code, Cursor, …) to your vtiger CRM to
+**log timesheets** and **create / update records in any module** — in
+plain English.
+
+It talks to vtiger's built-in REST API (`/webservice.php`, available in
+vtiger 6.x / 7.x). It adds **no** access rules of its own: every call runs
+**as the authenticated user**, so vtiger enforces that user's role,
+profile, and row-level sharing automatically. Each person uses their own
+**Webservice Access Key**, so they only see and change what their account
+already allows.
+
+> New to the terminal? See **[SETUP.md](SETUP.md)** for a click-by-click,
+> non-developer guide.
+
+---
+
+## Features
+
+- 🔐 **Per-user auth** via each user's Webservice Access Key — row-level
+  access preserved, nothing centralized.
+- 🧩 **Any module**: `create`, `update`, `query`, `describe`, `retrieve`,
+  `delete` — subject to the user's permissions.
+- ⏱️ **Timesheet helpers** for the time-tracking module (create/list/update
+  entries, resolve tasks by name).
+- 🖥️ Ships as both an **MCP server** (for AI agents) and a **CLI**.
+- 📦 Zero changes to your vtiger install. Node 18+, no native deps.
+
+## Requirements
+
+- **Node.js 18+**
+- A vtiger CRM (6.x / 7.x) whose `/webservice.php` endpoint is reachable
+- Your **Webservice Access Key** — in the CRM: *My Preferences →
+  "Webservice Access Key"* (a 16-char string; **not** your login password)
+
+## Install
+
+```bash
+# Global (gives you the `vtiger` CLI and the `vtiger-mcp` server binary)
+npm install -g vtiger-mcp
+
+# …or run without installing
+npx vtiger-mcp        # starts the MCP server (stdio)
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/ViralP17/vtiger-mcp.git
+cd vtiger-mcp
+npm install
+npm run build
+```
+
+## Configure
+
+Set three environment variables (via your MCP client config, or a `.env`
+file for the CLI — see [.env.example](.env.example)):
+
+| Variable | Example | Notes |
+|---|---|---|
+| `VTIGER_URL` | `https://yourcrmdomain.com` | Base URL, no `/webservice.php` |
+| `VTIGER_USERNAME` | `your.username` | Your vtiger login |
+| `VTIGER_ACCESS_KEY` | `xxxxxxxxxxxxxxxx` | Webservice Access Key |
+| `VTIGER_ALLOW_DELETE` | `false` | Set `true` to allow `delete` |
+
+## Use as an MCP server
+
+Point your AI client at `vtiger-mcp` and pass your credentials in `env`.
+
+**Via npx (after `npm install -g vtiger-mcp` or letting npx fetch it):**
+
+```json
+{
+  "mcpServers": {
+    "vtiger": {
+      "command": "npx",
+      "args": ["-y", "vtiger-mcp"],
+      "env": {
+        "VTIGER_URL": "https://yourcrmdomain.com",
+        "VTIGER_USERNAME": "your.username",
+        "VTIGER_ACCESS_KEY": "your-access-key",
+        "VTIGER_ALLOW_DELETE": "false"
+      }
+    }
+  }
+}
+```
+
+**From a source checkout** (use `node` + the built server path):
+
+```json
+{
+  "mcpServers": {
+    "vtiger": {
+      "command": "node",
+      "args": ["/path/to/vtiger-mcp/dist/mcp/server.js"],
+      "env": { "VTIGER_URL": "https://yourcrmdomain.com", "VTIGER_USERNAME": "your.username", "VTIGER_ACCESS_KEY": "your-access-key" }
+    }
+  }
+}
+```
+
+- **Claude Desktop** config: `%APPDATA%\Claude\claude_desktop_config.json`
+  (Windows) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+- **Cursor / Claude Code**: a `.mcp.json` with the same `mcpServers` shape
+
+Then just ask, e.g. *"Log 3 hours to the Website Redesign task today as
+regular hours"* or *"Show my timesheets this week."*
+
+## Use as a CLI
+
+```bash
+export VTIGER_URL=https://yourcrmdomain.com
+export VTIGER_USERNAME=your.username
+export VTIGER_ACCESS_KEY=your-access-key   # or put these in a .env file
+
+vtiger whoami
+vtiger modules
+vtiger describe TimeControl
+vtiger query "SELECT tc_code, date_start, totaltime FROM TimeControl LIMIT 5;"
+vtiger log-timesheet --task "Website Redesign" --start 10:00 --end 13:00 --type "Regular Hours" --activity "API work"
+vtiger my-timesheets --from 2026-07-01 --to 2026-07-31
+vtiger create ProjectTask --set projecttaskname="Write docs" --set projectid=<id>
+vtiger update 17x1234 --set description="Revised notes"
+```
+
+## Tools exposed to the AI agent
+
+**Any module (scoped to your access):**
+
+| Tool | What it does |
+|---|---|
+| `list_modules` | Modules you can access |
+| `describe_module` | Live fields of a module (names, mandatory, picklists, references) |
+| `query` | Read-only VTQL `SELECT` |
+| `retrieve_record` | Fetch one record by id |
+| `create_record` | Create a record in any writable module |
+| `update_record` | Partial update of a record |
+| `delete_record` | Delete (only if `VTIGER_ALLOW_DELETE=true`) |
+
+**Timesheet helpers (the time-tracking module):**
+
+| Tool | What it does |
+|---|---|
+| `whoami` | Your vtiger user id / profile |
+| `list_my_projects` | Projects you can access |
+| `list_my_tasks` | Project tasks (for the `related_to` link) |
+| `log_timesheet` | Add a daily entry (resolves task, defaults date/owner, computes total) |
+| `list_my_timesheets` | Your entries in a date range |
+| `update_timesheet` | Edit an existing entry |
+
+## Notes & tips
+
+- **Field names vary per install.** vtiger schemas are customizable, so
+  always `describe_module` (or `vtiger describe <Module>`) first to learn
+  the exact field names before creating/updating.
+- **Ids** are vtiger "webservice ids" like `17x1234`
+  (`<moduleId>x<recordId>`). Reference fields (owner, `related_to`,
+  `projectid`) expect these ids; the timesheet helpers resolve task names
+  to ids for you.
+- **The timesheet module name** in this tool defaults to `TimeControl`.
+  If your install uses a different module for time tracking, use the
+  generic `create_record` / `query` tools, or adjust the constants in
+  `src/core/timesheet.ts`.
+- **Deletes are off by default.** Set `VTIGER_ALLOW_DELETE=true` only if you
+  want the agent/CLI to delete records (and your account has that right).
+- **Security.** Your access key is a secret — keep it in your local `.env`
+  or client config only. Use HTTPS. Nothing is centralized; each user runs
+  their own copy with their own key.
+
+## License
+
+[MIT](LICENSE) © ViralP17

package/SETUP.md

@@ -0,0 +1,182 @@
+# Setup Guide — for everyone (no coding needed)
+
+This lets you **log your daily timesheet (Time Control) and add/update
+records in the vtiger portal just by chatting** with an AI assistant
+(Claude Desktop). After a one-time setup, you never touch any code or
+terminal — you simply type things like:
+
+> "Log 4 hours to the Website Redesign task today as regular hours."
+> "Show my timesheets for this week."
+> "Add a 2 hour entry to task X yesterday: fixed the login bug."
+
+The assistant does it using **your own** vtiger account, so you can only
+see and change what you're already allowed to in the portal.
+
+---
+
+## What you need (once)
+
+1. **Node.js** — free. Install the **LTS** version from <https://nodejs.org/>
+   (just click through the installer with defaults).
+2. **Claude Desktop** — the app you'll chat in. Download from
+   <https://claude.ai/download> and sign in.
+3. **This `vtiger-mcp` folder** on your computer (ask your team lead for
+   it, or clone the repo).
+4. **Your Webservice Access Key** (see next section).
+
+### How to find your Webservice Access Key
+
+This is **not** your login password.
+
+1. Log in to your vtiger CRM (e.g. https://yourcrmdomain.com).
+2. Click your **name** at the top-right → **My Preferences**.
+3. Scroll to the field **"Webservice Access Key"** (a 16-character code).
+4. Copy it. You'll paste it once during setup.
+
+> If that field is empty, ask an admin to re-save your user record so a
+> key gets generated.
+
+---
+
+## Track A — Easiest (Windows + Claude Desktop)
+
+A helper script does everything for you.
+
+1. Open the `vtiger-mcp` folder in File Explorer.
+2. **Right-click `setup.ps1` → "Run with PowerShell".**
+   - If Windows blocks it, open PowerShell and run:
+     `powershell -ExecutionPolicy Bypass -File setup.ps1`
+3. Answer the two prompts:
+   - **Portal URL** — just press Enter to accept the default.
+   - **Username** — your vtiger login (e.g. `jsmith`).
+   - **Access Key** — paste the key from My Preferences.
+4. When it says *"Config written"*, **fully quit Claude Desktop**
+   (right-click the tray icon → Quit) and **open it again**.
+5. Start chatting — try: *"Show my timesheets for this week."*
+
+That's it. You're done. 🎉
+
+---
+
+## Track B — Manual setup (Mac/Linux, or Cursor / Claude Code)
+
+If you're not on Windows, or you use a different AI client, add the
+config by hand.
+
+1. In a terminal, inside the `vtiger-mcp` folder, run once:
+   ```
+   npm install
+   npm run build
+   ```
+2. Note the **full path** to `dist/mcp/server.js` inside this folder.
+3. Open your client's config file and add the `vtiger` block below,
+   replacing the path and your details. A ready template is in
+   [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json).
+
+   **Claude Desktop config location:**
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+   **Cursor:** a `.mcp.json` in your project (same `mcpServers` shape).
+   **Claude Code:** run `claude mcp add` or edit `.mcp.json`.
+
+   ```json
+   {
+     "mcpServers": {
+       "vtiger": {
+         "command": "node",
+         "args": ["/full/path/to/vtiger-mcp/dist/mcp/server.js"],
+         "env": {
+           "VTIGER_URL": "https://yourcrmdomain.com",
+           "VTIGER_USERNAME": "your.username",
+           "VTIGER_ACCESS_KEY": "your-access-key",
+           "VTIGER_ALLOW_DELETE": "false"
+         }
+       }
+     }
+   }
+   ```
+4. Fully restart the client.
+
+---
+
+## What you can ask for
+
+Timesheets (the daily Time Control entries):
+- *"Log a timesheet: task 'Website Redesign', 9:00 to 13:00 today, regular hours, note 'team meeting + planning'."*
+- *"Add 3 hours to task X yesterday as extra hours."*
+- *"What tasks can I log time against?"* (lists your project tasks)
+- *"Show my timesheets between 1 and 13 July."*
+- *"Change the note on my last entry to '…'."*
+
+Any other module you have access to:
+- *"Create a project task called 'Write docs' under project Y."*
+- *"Find contacts whose name contains 'Patel'."* (read-only search)
+- *"Update record 17x1234: set the status to In Progress."*
+
+The assistant will ask for anything it needs (like which task you mean)
+and will show you what it created.
+
+---
+
+## Already using other MCP servers?
+
+Track A **overwrites** `claude_desktop_config.json` (it saves a
+`.backup` first). If you already have other servers configured, open the
+`.backup` file and copy their entries into the new file's `mcpServers`
+object, next to `"vtiger"`. Each server is just one more key:
+
+```json
+"mcpServers": {
+  "vtiger": { ... },
+  "some-other-server": { ... }
+}
+```
+
+---
+
+## Troubleshooting
+
+- **"vtiger" tools don't appear in Claude Desktop** → make sure you
+  *fully quit* and reopened it (not just closed the window). Check the
+  config file has no typos (valid JSON).
+- **"Access key for the user is undefined" / login fails** → the Access
+  Key is wrong or empty. Re-copy it from My Preferences.
+- **403 Forbidden / can't connect** → the portal's `webservice.php` must
+  be reachable (an admin one-time change). Contact your team lead.
+- **"Permission … denied" when creating/deleting** → your vtiger account
+  doesn't have that right. This is expected — the tool respects your
+  portal permissions.
+- **Deleting is blocked** → deletes are off by default for safety. An
+  admin can enable it by setting `VTIGER_ALLOW_DELETE` to `true` in the
+  config, if your account even has delete rights.
+
+---
+
+## Fastest path for developers (npm)
+
+If you're comfortable editing a JSON config, you don't need this folder at
+all — the package is on npm. Just point your client at it with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "vtiger": {
+      "command": "npx",
+      "args": ["-y", "vtiger-mcp"],
+      "env": {
+        "VTIGER_URL": "https://yourcrmdomain.com",
+        "VTIGER_USERNAME": "your.username",
+        "VTIGER_ACCESS_KEY": "your-access-key",
+        "VTIGER_ALLOW_DELETE": "false"
+      }
+    }
+  }
+}
+```
+
+`npx` fetches and runs `vtiger-mcp` automatically. For a CLI, run
+`npm install -g vtiger-mcp` then use `vtiger …` (see the main README).
+
+For non-developers on Windows, **Track A (`setup.ps1`)** remains the
+simplest per-person path.

package/dist/cli/index.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createClientFromEnv } from "../core/client.js";
+import { TIMESHEET_MODULE, PROJECT_MODULE, findTasks, buildTimesheetElement, listMyTimesheets, } from "../core/timesheet.js";
+/**
+ * Thin CLI over the shared vtiger core client. Useful for quick testing,
+ * scripting, and for developers who prefer the terminal. Reads the same
+ * env vars as the MCP server; also loads a local .env if present.
+ */
+// --- minimal .env loader (no dependency) ---------------------------------
+function loadEnv() {
+    const path = resolve(process.cwd(), ".env");
+    if (!existsSync(path))
+        return;
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        let value = trimmed.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (process.env[key] === undefined)
+            process.env[key] = value;
+    }
+}
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("--")) {
+            const key = token.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                (flags[key] ??= []).push(next);
+                i++;
+            }
+            else {
+                (flags[key] ??= []).push("true");
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { positionals, flags };
+}
+function flag(args, name) {
+    return args.flags[name]?.[0];
+}
+/** Turn repeated `--set field=value` into an object. */
+function collectSet(args) {
+    const out = {};
+    for (const pair of args.flags["set"] ?? []) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            throw new Error(`--set expects field=value, got "${pair}"`);
+        out[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return out;
+}
+function print(data) {
+    process.stdout.write((typeof data === "string" ? data : JSON.stringify(data, null, 2)) + "\n");
+}
+const USAGE = `vtiger — CLI for vtiger CRM
+
+Usage:
+  vtiger whoami
+  vtiger modules
+  vtiger describe <Module>
+  vtiger query "<VTQL SELECT>"
+  vtiger retrieve <id>
+  vtiger create <Module> --set field=value [--set ...]
+  vtiger update <id> --set field=value [--set ...]
+  vtiger delete <id>                         (needs VTIGER_ALLOW_DELETE=true)
+
+  vtiger projects
+  vtiger tasks [nameFragment]
+  vtiger log-timesheet [--date YYYY-MM-DD] [--task "<name or id>"]
+                       [--start HH:MM] [--end HH:MM] [--total HH:MM]
+                       [--activity "..."] [--type "Regular Hours"]
+  vtiger my-timesheets [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+
+Credentials come from env (VTIGER_URL / VTIGER_USERNAME / VTIGER_ACCESS_KEY)
+or a local .env file.`;
+async function main() {
+    loadEnv();
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    const args = parseArgs(argv.slice(1));
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        print(USAGE);
+        return;
+    }
+    const client = createClientFromEnv();
+    switch (command) {
+        case "whoami": {
+            await client.listTypes();
+            let user = null;
+            try {
+                const rows = await client.query(`SELECT id, user_name, first_name, last_name, email1 FROM Users WHERE id = '${client.userId}';`);
+                user = rows[0] ?? null;
+            }
+            catch {
+                // Non-admin users cannot query the Users module; userId alone is enough.
+            }
+            print({ userId: client.userId, user });
+            break;
+        }
+        case "modules":
+            print(await client.listTypes());
+            break;
+        case "describe": {
+            const module = args.positionals[0];
+            if (!module)
+                throw new Error("Usage: vtiger describe <Module>");
+            print(await client.describe(module));
+            break;
+        }
+        case "query": {
+            const vtql = args.positionals[0];
+            if (!vtql)
+                throw new Error('Usage: vtiger query "<VTQL SELECT>"');
+            print(await client.query(vtql));
+            break;
+        }
+        case "retrieve": {
+            const id = args.positionals[0];
+            if (!id)
+                throw new Error("Usage: vtiger retrieve <id>");
+            print(await client.retrieve(id));
+            break;
+        }
+        case "create": {
+            const module = args.positionals[0];
+            if (!module)
+                throw new Error("Usage: vtiger create <Module> --set field=value");
+            print(await client.create(module, collectSet(args)));
+            break;
+        }
+        case "update": {
+            const id = args.positionals[0];
+            if (!id)
+                throw new Error("Usage: vtiger update <id> --set field=value");
+            print(await client.revise({ id, ...collectSet(args) }));
+            break;
+        }
+        case "delete": {
+            const id = args.positionals[0];
+            if (!id)
+                throw new Error("Usage: vtiger delete <id>");
+            print(await client.delete(id));
+            break;
+        }
+        case "projects":
+            print(await client.query(`SELECT id, projectname, projectstatus FROM ${PROJECT_MODULE} ORDER BY projectname LIMIT 100;`));
+            break;
+        case "tasks":
+            print(await findTasks(client, args.positionals[0] ?? ""));
+            break;
+        case "log-timesheet": {
+            await client.listTypes(); // ensure login -> userId
+            let taskId;
+            const task = flag(args, "task");
+            if (task) {
+                const matches = await findTasks(client, task);
+                if (matches.length === 0)
+                    throw new Error(`No task matches "${task}".`);
+                if (matches.length > 1) {
+                    print({ message: `Multiple tasks match "${task}"; re-run with the exact id.`, candidates: matches });
+                    return;
+                }
+                taskId = matches[0].id;
+            }
+            const element = buildTimesheetElement({
+                date: flag(args, "date") ?? new Date().toISOString().slice(0, 10),
+                taskId,
+                startTime: flag(args, "start"),
+                endTime: flag(args, "end"),
+                totalTime: flag(args, "total"),
+                activity: flag(args, "activity"),
+                hoursType: flag(args, "type"),
+                assignedUserId: client.userId ?? undefined,
+            });
+            print(await client.create(TIMESHEET_MODULE, element));
+            break;
+        }
+        case "my-timesheets": {
+            await client.listTypes();
+            print(await listMyTimesheets(client, flag(args, "from"), flag(args, "to")));
+            break;
+        }
+        default:
+            print(`Unknown command: ${command}\n\n${USAGE}`);
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/core/client.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+/** Error thrown for any non-success vtiger response (carries the vtiger error code). */
+export class VtigerError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.name = "VtigerError";
+        this.code = code;
+    }
+}
+/** vtiger operations that read their input from $_GET (everything else is POST). */
+const GET_OPERATIONS = new Set([
+    "getchallenge",
+    "retrieve",
+    "query",
+    "describe",
+    "listtypes",
+    "retrieve_related",
+    "getupdates",
+]);
+function md5(input) {
+    return createHash("md5").update(input).digest("hex");
+}
+export class VtigerClient {
+    endpoint;
+    config;
+    session = null;
+    constructor(config) {
+        if (!config.url)
+            throw new Error("VTIGER_URL is required");
+        if (!config.username)
+            throw new Error("VTIGER_USERNAME is required");
+        if (!config.accessKey)
+            throw new Error("VTIGER_ACCESS_KEY is required");
+        this.config = config;
+        this.endpoint = config.url.replace(/\/+$/, "") + "/webservice.php";
+    }
+    /** The vtiger user id of the authenticated developer (e.g. "19x5"). Requires a prior login. */
+    get userId() {
+        return this.session?.userId ?? null;
+    }
+    // ---------------------------------------------------------------------------
+    // Low-level transport
+    // ---------------------------------------------------------------------------
+    /** Perform one HTTP call to webservice.php and unwrap the {success, result|error} envelope. */
+    async raw(operation, params) {
+        const method = GET_OPERATIONS.has(operation) ? "GET" : "POST";
+        const query = new URLSearchParams({ operation, ...params });
+        let response;
+        if (method === "GET") {
+            response = await fetch(`${this.endpoint}?${query.toString()}`, {
+                method: "GET",
+                headers: { Accept: "application/json" },
+            });
+        }
+        else {
+            response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: query.toString(),
+            });
+        }
+        const text = await response.text();
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            throw new VtigerError("NON_JSON_RESPONSE", `Expected JSON from webservice.php but got (HTTP ${response.status}): ${text.slice(0, 300)}`);
+        }
+        if (payload && payload.success === true)
+            return payload.result;
+        const err = payload?.error ?? {};
+        throw new VtigerError(err.code ?? "UNKNOWN_ERROR", err.message ?? "Unknown error");
+    }
+    isSessionError(err) {
+        if (!(err instanceof VtigerError))
+            return false;
+        const code = err.code.toUpperCase();
+        return (code.includes("SESSION") ||
+            code === "AUTHENTICATION_REQUIRED" ||
+            code === "AUTHREQUIRED");
+    }
+    // ---------------------------------------------------------------------------
+    // Authentication
+    // ---------------------------------------------------------------------------
+    /** Run the challenge/response handshake and cache the session. */
+    async login() {
+        const challenge = await this.raw("getchallenge", {
+            username: this.config.username,
+        });
+        const token = challenge.token;
+        const accessKey = md5(token + this.config.accessKey);
+        const result = await this.raw("login", {
+            username: this.config.username,
+            accessKey,
+        });
+        this.session = result;
+        return result;
+    }
+    /** Ensure we have a live session (login lazily). */
+    async ensureSession() {
+        if (!this.session)
+            await this.login();
+        return this.session;
+    }
+    /**
+     * Authenticated request with one automatic re-login + retry if the
+     * session has expired. `operation` selects GET vs POST automatically.
+     */
+    async call(operation, params = {}) {
+        const session = await this.ensureSession();
+        try {
+            return await this.raw(operation, { sessionName: session.sessionName, ...params });
+        }
+        catch (err) {
+            if (this.isSessionError(err)) {
+                const fresh = await this.login();
+                return await this.raw(operation, { sessionName: fresh.sessionName, ...params });
+            }
+            throw err;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Typed operation wrappers
+    // ---------------------------------------------------------------------------
+    /** Modules the current user may access. */
+    async listTypes() {
+        return this.call("listtypes");
+    }
+    /** Field metadata for a module (reflects the LIVE schema, incl. custom fields). */
+    async describe(elementType) {
+        return this.call("describe", { elementType });
+    }
+    /** Run a read-only VTQL SELECT. Returns an array of records. */
+    async query(vtql) {
+        return this.call("query", { query: vtql });
+    }
+    /** Fetch one record by its webservice id (e.g. "17x1234"). */
+    async retrieve(id) {
+        return this.call("retrieve", { id });
+    }
+    /** Create a record. `element` is a plain object of field => value. */
+    async create(elementType, element) {
+        return this.call("create", {
+            elementType,
+            element: JSON.stringify(element),
+        });
+    }
+    /** Full-record update (must include `id` and all mandatory fields). */
+    async update(element) {
+        return this.call("update", { element: JSON.stringify(element) });
+    }
+    /** Partial update — only the supplied fields change (must include `id`). */
+    async revise(element) {
+        return this.call("revise", { element: JSON.stringify(element) });
+    }
+    /** Delete a record by webservice id. Guarded by allowDelete. */
+    async delete(id) {
+        if (!this.config.allowDelete) {
+            throw new VtigerError("DELETE_DISABLED", "Deletion is disabled. Set VTIGER_ALLOW_DELETE=true to enable it.");
+        }
+        return this.call("delete", { id });
+    }
+}
+/** Build a client from the standard environment variables. */
+export function createClientFromEnv() {
+    return new VtigerClient({
+        url: process.env.VTIGER_URL ?? "",
+        username: process.env.VTIGER_USERNAME ?? "",
+        accessKey: process.env.VTIGER_ACCESS_KEY ?? "",
+        allowDelete: (process.env.VTIGER_ALLOW_DELETE ?? "false").toLowerCase() === "true",
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/core/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/core/timesheet.js

@@ -0,0 +1,110 @@
+import { isWebserviceId } from "./vtiger-id.js";
+/**
+ * Helpers for the daily timesheet module. The timesheet module in this
+ * portal is `TimeControl` (table vtiger_timecontrol) — NOT literally
+ * "Timesheet".
+ *
+ * The LIVE field set (verified via describe against production) is:
+ *   date_start, date_end (date), time_start, time_end (time HH:MM:SS),
+ *   related_to (-> ProjectTask), projectid (-> Project),
+ *   description (activity text), hours_type (picklist: Regular/Extra Hours),
+ *   assigned_user_id (owner, the only MANDATORY field),
+ *   totaltime/total_hour/total_min (computed server-side from the times),
+ *   tc_code (auto). We deliberately do NOT set the computed fields — the
+ *   module's save_module() derives them and rolls the hours up onto the
+ *   linked ProjectTask.
+ */
+export const TIMESHEET_MODULE = "TimeControl";
+export const TASK_MODULE = "ProjectTask";
+export const PROJECT_MODULE = "Project";
+/** Escape a value for safe inclusion inside a single-quoted VTQL string literal. */
+export function escapeVtql(value) {
+    // VTQL is SQL-like; single quotes are the string delimiter. Double them to escape.
+    return value.replace(/'/g, "''");
+}
+/** Normalise a clock time to vtiger's "HH:MM:SS" form (accepts "H:MM" or "HH:MM:SS"). */
+export function normalizeTime(t) {
+    const s = t.trim();
+    let m = /^(\d{1,2}):(\d{2}):(\d{2})$/.exec(s);
+    if (m)
+        return `${m[1].padStart(2, "0")}:${m[2]}:${m[3]}`;
+    m = /^(\d{1,2}):(\d{2})$/.exec(s);
+    if (m)
+        return `${m[1].padStart(2, "0")}:${m[2]}:00`;
+    throw new Error(`Invalid time "${t}" (expected HH:MM or HH:MM:SS)`);
+}
+/** Convert an explicit total ("H:MM" or a number of hours/seconds) to seconds. */
+export function parseTotalToSeconds(total) {
+    const s = total.trim();
+    const hm = /^(\d{1,2}):(\d{2})$/.exec(s);
+    if (hm)
+        return Number(hm[1]) * 3600 + Number(hm[2]) * 60;
+    if (/^\d+$/.test(s))
+        return Number(s) * 60; // bare number => minutes
+    throw new Error(`Invalid total "${total}" (expected "H:MM" or minutes)`);
+}
+/**
+ * Resolve a project task reference (used for the timesheet `related_to`
+ * field). Accepts either a webservice id (returned as-is) or a name to
+ * search for. Returns all matches so the caller can disambiguate.
+ */
+export async function findTasks(client, taskNameOrId) {
+    const trimmed = taskNameOrId.trim();
+    if (isWebserviceId(trimmed)) {
+        const rec = await client.retrieve(trimmed);
+        return [{ id: rec.id, name: rec.projecttaskname ?? trimmed, projectId: rec.projectid }];
+    }
+    const like = escapeVtql(trimmed);
+    const rows = await client.query(`SELECT id, projecttaskname, projectid FROM ${TASK_MODULE} WHERE projecttaskname LIKE '%${like}%' ORDER BY projecttaskname LIMIT 25;`);
+    return rows.map((r) => ({
+        id: r.id,
+        name: r.projecttaskname,
+        projectId: r.projectid,
+    }));
+}
+/**
+ * Assemble a TimeControl `element` object for `client.create`. Sets only
+ * the fields the caller supplied. When start/end times are given, the
+ * server computes totaltime/total_hour/total_min itself — so we leave
+ * those alone. An explicit `totalTime` (without times) is written to the
+ * seconds-based `totaltime` field.
+ */
+export function buildTimesheetElement(input) {
+    const element = {
+        date_start: input.date,
+        date_end: input.date,
+    };
+    if (input.assignedUserId)
+        element.assigned_user_id = input.assignedUserId;
+    if (input.taskId)
+        element.related_to = input.taskId;
+    if (input.projectId)
+        element.projectid = input.projectId;
+    if (input.startTime)
+        element.time_start = normalizeTime(input.startTime);
+    if (input.endTime)
+        element.time_end = normalizeTime(input.endTime);
+    if (input.activity)
+        element.description = input.activity;
+    if (input.hoursType)
+        element.hours_type = input.hoursType;
+    // Only set totaltime when we can't rely on server computation from times.
+    if (input.totalTime && !(input.startTime && input.endTime)) {
+        element.totaltime = parseTotalToSeconds(input.totalTime);
+    }
+    return element;
+}
+/** List the authenticated user's timesheet entries within a date range. */
+export async function listMyTimesheets(client, from, to) {
+    const clauses = [];
+    const uid = client.userId;
+    if (uid)
+        clauses.push(`assigned_user_id = '${uid}'`);
+    if (from)
+        clauses.push(`date_start >= '${escapeVtql(from)}'`);
+    if (to)
+        clauses.push(`date_start <= '${escapeVtql(to)}'`);
+    const where = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+    return client.query(`SELECT id, tc_code, date_start, time_start, time_end, totaltime, description, hours_type, related_to FROM ${TIMESHEET_MODULE}${where} ORDER BY date_start DESC LIMIT 100;`);
+}
+//# sourceMappingURL=timesheet.js.map

package/dist/core/timesheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timesheet.js","sourceRoot":"","sources":["../../src/core/timesheet.ts"],"names":[],"mappings":"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"}

package/dist/core/vtiger-id.js

@@ -0,0 +1,19 @@
+/**
+ * vtiger identifies records with a composite "webservice id" of the form
+ * `<moduleEntityId>x<recordId>`, e.g. "17x1234". These helpers make it
+ * safe to detect and work with that format.
+ */
+const WS_ID_RE = /^\d+x\d+$/;
+/** True if `value` looks like a vtiger webservice id (e.g. "17x1234"). */
+export function isWebserviceId(value) {
+    return WS_ID_RE.test(value.trim());
+}
+/** Split a webservice id into its module and record parts. */
+export function splitId(id) {
+    if (!isWebserviceId(id)) {
+        throw new Error(`Not a valid vtiger webservice id: "${id}" (expected "<num>x<num>")`);
+    }
+    const [moduleId, recordId] = id.split("x");
+    return { moduleId, recordId };
+}
+//# sourceMappingURL=vtiger-id.js.map

package/dist/core/vtiger-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vtiger-id.js","sourceRoot":"","sources":["../../src/core/vtiger-id.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,QAAQ,GAAG,WAAW,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,sCAAsC,EAAE,4BAA4B,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC"}

package/dist/mcp/server.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createClientFromEnv } from "../core/client.js";
+import { TIMESHEET_MODULE, PROJECT_MODULE, findTasks, buildTimesheetElement, listMyTimesheets, } from "../core/timesheet.js";
+/**
+ * MCP stdio server that exposes the vtiger portal to an AI agent AS the
+ * configured developer. Credentials come from env (VTIGER_URL /
+ * VTIGER_USERNAME / VTIGER_ACCESS_KEY); vtiger enforces that developer's
+ * own row-level access, so every tool is inherently scoped to them.
+ */
+// Lazily build the client so a missing-credential error surfaces as a clean
+// tool error rather than crashing the transport at startup.
+let cached = null;
+function getClient() {
+    if (!cached)
+        cached = createClientFromEnv();
+    return cached;
+}
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+function ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+function fail(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+const server = new McpServer({ name: "vtiger-mcp", version: "0.1.0" });
+/**
+ * Register a tool with uniform error handling. `server.tool` is cast to
+ * sidestep the SDK's heavily-overloaded typings; the runtime contract
+ * (name, description, zod shape, async handler -> {content,...}) is exact.
+ */
+function tool(name, description, shape, handler) {
+    server.tool(name, description, shape, async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Generic, any-module tools (subject to the developer's own permissions)
+// ---------------------------------------------------------------------------
+tool("list_modules", "List the vtiger modules (entity types) the authenticated developer is allowed to access.", {}, async () => ok(await getClient().listTypes()));
+tool("describe_module", "Describe a module's live fields: names, labels, mandatory flags, types, picklist values and reference targets. Call this before create/update to learn the exact field names (the schema is customized).", { module: z.string().describe("Module name, e.g. 'TimeControl', 'ProjectTask', 'Contacts'.") }, async ({ module }) => ok(await getClient().describe(module)));
+tool("query", "Run a read-only VTQL SELECT (SQL-like). Results are already filtered to what the developer may see. Example: SELECT tc_code, date_start, totaltime FROM TimeControl LIMIT 10;", { vtql: z.string().describe("A VTQL SELECT statement. Include a LIMIT. Must start with SELECT.") }, async ({ vtql }) => {
+    if (!/^\s*select\b/i.test(vtql)) {
+        throw new Error("Only read-only SELECT queries are allowed here. Use create/update tools to modify data.");
+    }
+    return ok(await getClient().query(vtql));
+});
+tool("retrieve_record", "Fetch one record by its vtiger webservice id (e.g. '17x1234').", { id: z.string().describe("Webservice id, format <moduleId>x<recordId>.") }, async ({ id }) => ok(await getClient().retrieve(id)));
+tool("create_record", "Create a record in any module the developer can write to. Provide field values as an object; use describe_module first to get exact field names. Reference fields (owners, related records) take webservice ids.", {
+    module: z.string().describe("Target module name, e.g. 'ProjectTask'."),
+    values: z.record(z.any()).describe("Field name -> value map for the new record."),
+}, async ({ module, values }) => ok(await getClient().create(module, values)));
+tool("update_record", "Update fields on an existing record (partial update — only supplied fields change). Uses vtiger 'revise'.", {
+    id: z.string().describe("Webservice id of the record to update."),
+    values: z.record(z.any()).describe("Field name -> new value map."),
+}, async ({ id, values }) => ok(await getClient().revise({ id, ...values })));
+tool("delete_record", "Delete a record by webservice id. Disabled unless the server was started with VTIGER_ALLOW_DELETE=true.", { id: z.string().describe("Webservice id of the record to delete.") }, async ({ id }) => ok(await getClient().delete(id)));
+// ---------------------------------------------------------------------------
+// Timesheet convenience tools (TimeControl module)
+// ---------------------------------------------------------------------------
+tool("whoami", "Return the authenticated developer's vtiger user id and profile info.", {}, async () => {
+    const client = getClient();
+    await client.listTypes(); // forces login so userId is populated
+    let user = null;
+    try {
+        const rows = await client.query(`SELECT id, user_name, first_name, last_name, email1 FROM Users WHERE id = '${client.userId}';`);
+        user = rows[0] ?? null;
+    }
+    catch {
+        // Non-admin users cannot query the Users module; the userId alone is enough.
+    }
+    return ok({ userId: client.userId, user });
+});
+tool("list_my_projects", "List projects the developer can access (id + name), to pick a project for timesheet logging.", {}, async () => ok(await getClient().query(`SELECT id, projectname, projectstatus FROM ${PROJECT_MODULE} ORDER BY projectname LIMIT 100;`)));
+tool("list_my_tasks", "List project tasks (id + name) the developer can access. Optionally filter by a project-task name fragment. The task id is what a timesheet's 'related_to' links to.", { nameContains: z.string().optional().describe("Optional substring to match against the task name.") }, async ({ nameContains }) => ok(await findTasks(getClient(), nameContains ?? "")));
+tool("log_timesheet", "Log a daily timesheet entry in the TimeControl module for the developer. Resolves a task by name or id, defaults the date to today and the owner to the current user, and computes total time from start/end when not given.", {
+    date: z.string().optional().describe("Entry date YYYY-MM-DD. Defaults to today."),
+    task: z.string().optional().describe("Project task name (searched) or webservice id, linked as related_to."),
+    startTime: z.string().optional().describe("Clock start HH:MM, e.g. '10:00'."),
+    endTime: z.string().optional().describe("Clock end HH:MM, e.g. '13:00'."),
+    totalTime: z.string().optional().describe("Explicit total HH:MM; computed from start/end if omitted."),
+    activity: z.string().optional().describe("Free-text description of the work."),
+    hoursType: z.string().optional().describe("Picklist value, e.g. 'Regular Hours' or 'Extra Hours'."),
+}, async (args) => {
+    const client = getClient();
+    await client.listTypes(); // ensure login -> userId available
+    let taskId;
+    if (args.task) {
+        const matches = await findTasks(client, args.task);
+        if (matches.length === 0) {
+            throw new Error(`No project task found matching "${args.task}". Use list_my_tasks to browse.`);
+        }
+        if (matches.length > 1) {
+            return ok({
+                needsDisambiguation: true,
+                message: `Multiple tasks match "${args.task}". Re-call log_timesheet with the exact task id.`,
+                candidates: matches,
+            });
+        }
+        taskId = matches[0].id;
+    }
+    const element = buildTimesheetElement({
+        date: args.date ?? today(),
+        taskId,
+        startTime: args.startTime,
+        endTime: args.endTime,
+        totalTime: args.totalTime,
+        activity: args.activity,
+        hoursType: args.hoursType,
+        assignedUserId: client.userId ?? undefined,
+    });
+    const created = await client.create(TIMESHEET_MODULE, element);
+    return ok({ created });
+});
+tool("list_my_timesheets", "List the developer's own timesheet entries, optionally within a date range (YYYY-MM-DD).", {
+    from: z.string().optional().describe("Start date inclusive, YYYY-MM-DD."),
+    to: z.string().optional().describe("End date inclusive, YYYY-MM-DD."),
+}, async ({ from, to }) => {
+    const client = getClient();
+    await client.listTypes(); // ensure login -> userId available
+    return ok(await listMyTimesheets(client, from, to));
+});
+tool("update_timesheet", "Update fields on an existing TimeControl timesheet entry (partial update).", {
+    id: z.string().describe("Webservice id of the TimeControl record."),
+    date: z.string().optional().describe("New date YYYY-MM-DD."),
+    startTime: z.string().optional(),
+    endTime: z.string().optional(),
+    totalTime: z.string().optional(),
+    activity: z.string().optional(),
+    hoursType: z.string().optional(),
+}, async ({ id, date, startTime, endTime, totalTime, activity, hoursType }) => {
+    const values = {};
+    if (date) {
+        values.date_start = date;
+        values.date_end = date;
+    }
+    if (startTime)
+        values.time_start = startTime;
+    if (endTime)
+        values.time_end = endTime;
+    if (totalTime)
+        values.totaltime = totalTime;
+    if (activity)
+        values.description = activity;
+    if (hoursType)
+        values.hours_type = hoursType;
+    return ok(await getClient().revise({ id, ...values }));
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs; stdout is the MCP channel.
+    process.stderr.write("vtiger-mcp server ready (stdio)\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAe,MAAM,KAAK,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAgB,MAAM,mBAAmB,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,cAAc,EAEd,SAAS,EACT,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AAEH,4EAA4E;AAC5E,4DAA4D;AAC5D,IAAI,MAAM,GAAwB,IAAI,CAAC;AACvC,SAAS,SAAS;IAChB,IAAI,CAAC,MAAM;QAAE,MAAM,GAAG,mBAAmB,EAAE,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,KAAK;IACZ,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAOD,SAAS,EAAE,CAAC,IAAa;IACvB,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,IAAI,CAAC,GAAY;IACxB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACnF,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AAEvE;;;;GAIG;AACH,SAAS,IAAI,CACX,IAAY,EACZ,WAAmB,EACnB,KAAQ,EACR,OAA2E;IAE1E,MAAM,CAAC,IAAY,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;QACjE,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAE9E,IAAI,CACF,cAAc,EACd,0FAA0F,EAC1F,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,SAAS,EAAE,CAAC,CAC9C,CAAC;AAEF,IAAI,CACF,iBAAiB,EACjB,0MAA0M,EAC1M,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC,EAAE,EAC9F,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAC7D,CAAC;AAEF,IAAI,CACF,OAAO,EACP,+KAA+K,EAC/K,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mEAAmE,CAAC,EAAE,EAClG,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IACjB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3C,CAAC,CACF,CAAC;AAEF,IAAI,CACF,iBAAiB,EACjB,gEAAgE,EAChE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC,EAAE,EAC3E,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CACrD,CAAC;AAEF,IAAI,CACF,eAAe,EACf,kNAAkN,EAClN;IACE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;CAClF,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAC3E,CAAC;AAEF,IAAI,CACF,eAAe,EACf,2GAA2G,EAC3G;IACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IACjE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CACnE,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAC1E,CAAC;AAEF,IAAI,CACF,eAAe,EACf,yGAAyG,EACzG,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC,EAAE,EACrE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CACnD,CAAC;AAEF,8EAA8E;AAC9E,mDAAmD;AACnD,8EAA8E;AAE9E,IAAI,CACF,QAAQ,EACR,uEAAuE,EACvE,EAAE,EACF,KAAK,IAAI,EAAE;IACT,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,sCAAsC;IAChE,IAAI,IAAI,GAAQ,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAC7B,8EAA8E,MAAM,CAAC,MAAM,IAAI,CAChG,CAAC;QACF,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;IAC/E,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC,CACF,CAAC;AAEF,IAAI,CACF,kBAAkB,EAClB,8FAA8F,EAC9F,EAAE,EACF,KAAK,IAAI,EAAE,CACT,EAAE,CACA,MAAM,SAAS,EAAE,CAAC,KAAK,CACrB,8CAA8C,cAAc,kCAAkC,CAC/F,CACF,CACJ,CAAC;AAEF,IAAI,CACF,eAAe,EACf,sKAAsK,EACtK,EAAE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC,EAAE,EACtG,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,SAAS,CAAC,SAAS,EAAE,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC,CACjF,CAAC;AAEF,IAAI,CACF,eAAe,EACf,8NAA8N,EAC9N;IACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACjF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sEAAsE,CAAC;IAC5G,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC7E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACzE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC;IACtG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC9E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;CACpG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,mCAAmC;IAE7D,IAAI,MAA0B,CAAC;IAC/B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,CAAC,IAAI,iCAAiC,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;gBACR,mBAAmB,EAAE,IAAI;gBACzB,OAAO,EAAE,yBAAyB,IAAI,CAAC,IAAI,kDAAkD;gBAC7F,UAAU,EAAE,OAAO;aACpB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,GAAG,qBAAqB,CAAC;QACpC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE;QAC1B,MAAM;QACN,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,cAAc,EAAE,MAAM,CAAC,MAAM,IAAI,SAAS;KAC3C,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC/D,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;AACzB,CAAC,CACF,CAAC;AAEF,IAAI,CACF,oBAAoB,EACpB,0FAA0F,EAC1F;IACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACzE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;CACtE,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE;IACrB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,mCAAmC;IAC7D,OAAO,EAAE,CAAC,MAAM,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC,CACF,CAAC;AAEF,IAAI,CACF,kBAAkB,EAClB,4EAA4E,EAC5E;IACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IACnE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAC5D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;IACzE,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;IACzB,CAAC;IACD,IAAI,SAAS;QAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7C,IAAI,OAAO;QAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC;IACvC,IAAI,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5C,IAAI,QAAQ;QAAE,MAAM,CAAC,WAAW,GAAG,QAAQ,CAAC;IAC5C,IAAI,SAAS;QAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC,CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;AAC5D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/examples/claude_desktop_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "vtiger": {
+      "command": "node",
+      "args": ["C:\\path\\to\\vtiger-mcp\\dist\\mcp\\server.js"],
+      "env": {
+        "VTIGER_URL": "https://yourcrmdomain.com",
+        "VTIGER_USERNAME": "your.username",
+        "VTIGER_ACCESS_KEY": "your-16-char-access-key",
+        "VTIGER_ALLOW_DELETE": "false"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "vtiger-mcp",
+  "version": "0.1.0",
+  "description": "MCP server + CLI for vtiger CRM — log timesheets and create/update records in any module via an AI agent, using each user's own webservice access key (row-level access preserved).",
+  "type": "module",
+  "bin": {
+    "vtiger": "dist/cli/index.js",
+    "vtiger-mcp": "dist/mcp/server.js"
+  },
+  "main": "dist/mcp/server.js",
+  "files": [
+    "dist",
+    "examples",
+    "SETUP.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "mcp": "node dist/mcp/server.js",
+    "cli": "node dist/cli/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "vtiger",
+    "vtiger-crm",
+    "mcp",
+    "model-context-protocol",
+    "crm",
+    "timesheet",
+    "cli",
+    "ai",
+    "claude"
+  ],
+  "author": "ViralP17",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ViralP17/vtiger-mcp.git"
+  },
+  "homepage": "https://github.com/ViralP17/vtiger-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ViralP17/vtiger-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}