vtiger-mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2026-07-13
+
+### Added
+- Copy-paste **AI-agent install prompt** in the README — paste it into any
+  file-editing AI agent to install and configure vtiger-mcp automatically.
+- **CLIENTS.md** — per-client setup for Claude Desktop/Code, Cursor,
+  Windsurf, Google Antigravity, VS Code (Copilot), OpenAI Codex CLI, Gemini
+  CLI, and any MCP client.
+- README badges (npm version, license, node).
+
+### Changed
+- Ship `CLIENTS.md` and `CHANGELOG.md` inside the published npm package.
+
+## [0.2.0] - 2026-07-13
+
+### Added
+- **Configurable timesheet module.** The timesheet helpers default to
+  `TimeControl` but now work on any vtiger install without code changes,
+  via `VTIGER_TIMESHEET_MODULE`, `VTIGER_TASK_MODULE`,
+  `VTIGER_PROJECT_MODULE`, and optional `VTIGER_TS_*_FIELD` field-name
+  overrides (see `.env.example`).
+- `CONTRIBUTING.md`, GitHub issue forms (bug / feature), and a PR template.
+
+### Notes
+- No breaking changes — defaults are unchanged for existing users.
+- The generic `create_record` / `update_record` / `query` /
+  `describe_module` tools work regardless of module names.
+
+## [0.1.0] - 2026-07-13
+
+### Added
+- First public release.
+- **MCP server** exposing vtiger CRM to AI agents, and a **CLI** over the
+  same core.
+- Generic tools (per-user access): `list_modules`, `describe_module`,
+  `query` (VTQL), `retrieve_record`, `create_record`, `update_record`,
+  `delete_record`.
+- Timesheet helpers: `whoami`, `list_my_projects`, `list_my_tasks`,
+  `log_timesheet`, `list_my_timesheets`, `update_timesheet`.
+- Per-user authentication via each user's Webservice Access Key, so
+  vtiger's role/profile and row-level sharing are preserved.
+- Deletes disabled by default (`VTIGER_ALLOW_DELETE=false`).
+
+[0.2.1]: https://github.com/ViralP17/vtiger-mcp/releases/tag/v0.2.1
+[0.2.0]: https://github.com/ViralP17/vtiger-mcp/releases/tag/v0.2.0
+[0.1.0]: https://github.com/ViralP17/vtiger-mcp/releases/tag/v0.1.0

package/CLIENTS.md

@@ -0,0 +1,137 @@
+# Connecting vtiger-mcp to your MCP client
+
+vtiger-mcp is a standard **stdio MCP server**, so it works with *any*
+MCP-compatible client. Most clients use the same JSON block — only the
+**file location** (or add command) differs.
+
+**The common block** (works in Claude Desktop, Claude Code, Cursor,
+Windsurf, Antigravity, Gemini CLI, and more):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+Get your **Webservice Access Key** from the CRM: *My Preferences →
+"Webservice Access Key"* (not your login password).
+
+> **Windows note:** if a GUI app can't find `npx`, either install globally
+> (`npm i -g vtiger-mcp`) and use `"command": "vtiger-mcp"`, or use
+> `"command": "node"` with the absolute path to the installed server, e.g.
+> `["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\vtiger-mcp\\dist\\mcp\\server.js"]`.
+
+---
+
+## Claude Desktop
+
+Config file:
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Paste the common block, then **fully quit and reopen** Claude Desktop.
+Windows one-click alternative: run [`setup.ps1`](setup.ps1) (see
+[SETUP.md](SETUP.md)).
+
+## Claude Code
+
+Add it in one command:
+
+```bash
+claude mcp add vtiger \
+  --env VTIGER_URL=https://yourcrmdomain.com \
+  --env VTIGER_USERNAME=your.username \
+  --env VTIGER_ACCESS_KEY=your-access-key \
+  -- npx -y vtiger-mcp
+```
+
+…or add the common block to a project `.mcp.json`.
+
+## Cursor
+
+Config file: `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json`
+(global). Paste the common block, then enable **vtiger** in
+*Settings → MCP*.
+
+## Windsurf (Codeium)
+
+Config file: `~/.codeium/windsurf/mcp_config.json`. Paste the common block
+and refresh MCP servers in the Cascade panel.
+
+## Google Antigravity
+
+Open **Settings → MCP / Agent tools → Add MCP server** and paste the common
+block (Antigravity uses the same `mcpServers` shape). If you prefer a file,
+use its `mcp_config.json` with the same content. Reload the MCP servers
+after saving.
+
+## VS Code (GitHub Copilot — Agent mode)
+
+Config file: `.vscode/mcp.json` (workspace). VS Code uses a top-level
+`servers` key and a `type`:
+
+```json
+{
+  "servers": {
+    "vtiger": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "vtiger-mcp"],
+      "env": {
+        "VTIGER_URL": "https://yourcrmdomain.com",
+        "VTIGER_USERNAME": "your.username",
+        "VTIGER_ACCESS_KEY": "your-access-key"
+      }
+    }
+  }
+}
+```
+
+Then open the Chat view in **Agent** mode and start the `vtiger` server.
+
+## OpenAI Codex CLI
+
+Config file: `~/.codex/config.toml` (TOML):
+
+```toml
+[mcp_servers.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" }
+```
+
+## Gemini CLI
+
+Config file: `~/.gemini/settings.json` (global) or `.gemini/settings.json`
+(project). Use the common `mcpServers` block. Or add via command:
+
+```bash
+gemini mcp add vtiger npx -y vtiger-mcp
+```
+
+(then set the `VTIGER_*` env vars in `settings.json`).
+
+## Any other MCP client
+
+Point it at the stdio command **`npx -y vtiger-mcp`** and provide the three
+`VTIGER_*` environment variables. That's all any MCP client needs.
+
+---
+
+### Verify it's connected
+
+Ask the agent *"list my vtiger modules"* or *"show my timesheets this
+week."* From a terminal you can sanity-check the same credentials with the
+CLI: `npx -y vtiger-mcp` is the server, while `npm i -g vtiger-mcp` gives
+you `vtiger whoami`, `vtiger describe TimeControl`, etc.

package/README.md

@@ -1,197 +1,247 @@
-# 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 is configurable** (see below). It defaults to
-  `TimeControl`; point it at your module without touching code.
-- **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.
-
-## Configuring the timesheet module (other vtiger installs)
-
-The timesheet helpers default to the `TimeControl` module with
-`ProjectTask`/`Project` links. If your install uses different module or
-field names, set these env vars (all optional) — no code changes needed:
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `VTIGER_TIMESHEET_MODULE` | `TimeControl` | Time-entry module |
-| `VTIGER_TASK_MODULE` | `ProjectTask` | Module linked from an entry |
-| `VTIGER_PROJECT_MODULE` | `Project` | Project module |
-
-Advanced field-name overrides (rarely needed): `VTIGER_TS_DATE_START_FIELD`,
-`VTIGER_TS_DATE_END_FIELD`, `VTIGER_TS_TIME_START_FIELD`,
-`VTIGER_TS_TIME_END_FIELD`, `VTIGER_TS_RELATED_FIELD`, `VTIGER_TS_DESC_FIELD`,
-`VTIGER_TS_HOURSTYPE_FIELD`, `VTIGER_TS_TOTAL_FIELD`, `VTIGER_TS_OWNER_FIELD`,
-`VTIGER_TASK_NAME_FIELD`, `VTIGER_TASK_PROJECT_FIELD`,
-`VTIGER_PROJECT_NAME_FIELD`. See [.env.example](.env.example) for the full
-list and defaults.
-
-> Whatever your modules are named, the generic `create_record`,
-> `update_record`, `query`, and `describe_module` tools always work.
-
-## License
-
-[MIT](LICENSE) © ViralP17
+# vtiger-mcp
+
+[![npm version](https://img.shields.io/npm/v/vtiger-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/vtiger-mcp)
+[![license: MIT](https://img.shields.io/npm/l/vtiger-mcp?color=blue)](LICENSE)
+[![node](https://img.shields.io/node/v/vtiger-mcp)](https://nodejs.org)
+
+**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.
+
+---
+
+## 🤖 Install with an AI agent (copy-paste prompt)
+
+Don't want to edit config files yourself? Copy the whole prompt below and
+paste it into an AI agent that can edit files (Claude Code, Cursor,
+Windsurf, Gemini CLI, OpenAI Codex, VS Code Copilot Agent, …). It will ask
+for your details and set everything up for you.
+
+```text
+Install and configure the "vtiger-mcp" MCP server for me (npm package name: vtiger-mcp).
+It lets me log vtiger CRM timesheets and create/update records in any module from this agent.
+
+Do this:
+1. Verify Node.js 18+ is installed (run: node --version). If it's missing, tell me to install
+   the LTS from https://nodejs.org and stop.
+2. Ask me for these and WAIT for my answers:
+   - VTIGER_URL: my vtiger base URL, e.g. https://yourcrmdomain.com (no /webservice.php)
+   - VTIGER_USERNAME: my vtiger login username
+   - VTIGER_ACCESS_KEY: my "Webservice Access Key" from vtiger -> My Preferences (NOT my password)
+3. Detect which MCP client I use and find its config file:
+   - Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) or
+     ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
+   - Cursor: ~/.cursor/mcp.json ; Windsurf: ~/.codeium/windsurf/mcp_config.json ;
+     Gemini CLI: ~/.gemini/settings.json  (all use the "mcpServers" JSON key)
+   - VS Code: ./.vscode/mcp.json  (uses a top-level "servers" key with "type": "stdio")
+   - OpenAI Codex CLI: ~/.codex/config.toml  (TOML table [mcp_servers.vtiger])
+   If you can't tell, ask me which client I'm using.
+4. Back up that file, then MERGE IN (do not overwrite my other servers) a server named "vtiger":
+   command: npx
+   args: ["-y", "vtiger-mcp"]
+   env: { VTIGER_URL, VTIGER_USERNAME, VTIGER_ACCESS_KEY, VTIGER_ALLOW_DELETE: "false" }
+   Use the correct shape for my client (mcpServers JSON, VS Code "servers", or Codex TOML).
+5. Keep my access key ONLY in this local config. Never commit it, echo it back in full, or share it.
+6. (Optional) Verify auth by running, with those env vars set:  npx -p vtiger-mcp vtiger whoami
+   It should print my vtiger userId.
+7. Tell me to fully quit and reopen my client, then try: "list my vtiger modules"
+   or "log 2 hours to <task name> today".
+```
+
+Prefer to do it manually? See **[CLIENTS.md](CLIENTS.md)** for every client's
+exact config.
+
+---
+
+## 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)
+
+> 📎 **Using Cursor, VS Code, Windsurf, Antigravity, OpenAI Codex CLI,
+> Gemini CLI, or another client?** See **[CLIENTS.md](CLIENTS.md)** for the
+> exact config file and format for each — it's the same server everywhere.
+
+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 is configurable** (see below). It defaults to
+  `TimeControl`; point it at your module without touching code.
+- **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.
+
+## Configuring the timesheet module (other vtiger installs)
+
+The timesheet helpers default to the `TimeControl` module with
+`ProjectTask`/`Project` links. If your install uses different module or
+field names, set these env vars (all optional) — no code changes needed:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `VTIGER_TIMESHEET_MODULE` | `TimeControl` | Time-entry module |
+| `VTIGER_TASK_MODULE` | `ProjectTask` | Module linked from an entry |
+| `VTIGER_PROJECT_MODULE` | `Project` | Project module |
+
+Advanced field-name overrides (rarely needed): `VTIGER_TS_DATE_START_FIELD`,
+`VTIGER_TS_DATE_END_FIELD`, `VTIGER_TS_TIME_START_FIELD`,
+`VTIGER_TS_TIME_END_FIELD`, `VTIGER_TS_RELATED_FIELD`, `VTIGER_TS_DESC_FIELD`,
+`VTIGER_TS_HOURSTYPE_FIELD`, `VTIGER_TS_TOTAL_FIELD`, `VTIGER_TS_OWNER_FIELD`,
+`VTIGER_TASK_NAME_FIELD`, `VTIGER_TASK_PROJECT_FIELD`,
+`VTIGER_PROJECT_NAME_FIELD`. See [.env.example](.env.example) for the full
+list and defaults.
+
+> Whatever your modules are named, the generic `create_record`,
+> `update_record`, `query`, and `describe_module` tools always work.
+
+## License
+
+[MIT](LICENSE) © ViralP17

package/dist/mcp/server.js

@@ -31,7 +31,7 @@ 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.2.0" });
+const server = new McpServer({ name: "vtiger-mcp", version: "0.2.1" });
 /**
  * Register a tool with uniform error handling. `server.tool` is cast to
  * sidestep the SDK's heavily-overloaded typings; the runtime contract

package/package.json

@@ -1,56 +1,58 @@
-{
-  "name": "vtiger-mcp",
-  "version": "0.2.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"
-  }
-}
+{
+  "name": "vtiger-mcp",
+  "version": "0.2.1",
+  "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",
+    "CLIENTS.md",
+    "CHANGELOG.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"
+  }
+}