FAC

Appearance

Changelog ​

Generated from the project's GitHub releases at build time — what ships is what you see here.

v3.1.0

2026-10-11

Frappe Assistant Core 3.1.0 ​

3.1.0 is a security release, and also the first feature release since 3.0.0. It hardens the run_python_code sandbox and tightens who can use the data tools. It also brings a large round of work on agents and workflows, FAC Chat and the MCP tools.

Upgrade promptly, especially if run_python_code is enabled on your site. Run bench migrate after updating. Two patches carry tool settings across.

Upgrade notes ​

  • run_python_code and run_database_query require System Manager. Until now any assistant-enabled user could call run_python_code. Users without the role no longer see either tool. FAC Tool Configuration cannot widen this.
  • analyze_business_data is removed. It was unused. Use run_python_code instead.
  • submit_document is now document_action. The old name still works as an alias for one more release. Update saved prompts, skills and MCP client configs. A migration patch moves the tool's FAC Tool Configuration settings to the new name.
  • send_email moved from the faco plugin to the core plugin. If you had switched faco off, the patch keeps send_email disabled. You can enable it from FAC Admin.
  • The pandas/numpy loaders (pd.read_*, np.load and similar) are no longer available inside run_python_code. Fetch data with data_query, frappe.get_list or tools.*. Code that read local files must change.

Security ​

run_python_code ​

Code run by run_python_code executes in a sandbox. In 3.0.0 and earlier that sandbox could be escaped. It has been reworked:

  • Every read goes through a permission-checked, read-only frappe stand-in. Results respect role permissions and User Permissions for the calling user, and nothing can be written.
  • Code is parsed and validated before it runs. A regular expression did this before. Imports, private and dunder attribute access, and the eval/exec family of builtins are rejected.
  • The import hook uses an explicit allowlist with no exception for modules whose name starts with an underscore.
  • pandas and numpy are exposed without their file, URL, SQL and pickle loaders, and without the functions that print host details. Everyday analysis (pd.offsets, pd.api, np.ma, np.linalg, np.random, …) is unchanged.
  • The tool requires the System Manager role.

These are in-process restrictions. Running the code under OS-level isolation is planned as a follow-up.

run_database_query ​

  • System Manager only.
  • Frappe's internal tables (such as __Auth) are refused.
  • File, lock and privilege statements (INTO OUTFILE, LOAD DATA, GRANT, LOCK TABLES, FOR UPDATE, SET, CALL, …) are refused. Validation uses a SQL lexer, so these keywords inside strings, comments and identifiers no longer cause false positives.
  • Results are capped at 1000 rows, even when the query sets a higher LIMIT.

Elsewhere ​

  • Workflow marketplace: importing or editing workflows requires System Manager, and import is denied by default.
  • Site registration: resending verification or changing the owner email of a pending site now requires the site's registration token.
  • FAC-Cloud-only tools: the browser and document-rendering tools are offered only to FAC Cloud, not to other MCP clients.

Agents and workflows ​

  • Builder: tool and loop nodes, with config panels and checks that mark invalid nodes. A workflow names a runtime user, and nodes run and test as that user. Graph layout is clearer, and the system prompt opens in a large editor.
  • Safer activation: activating a workflow warns about any write tool that is not set to run unattended. A setup checklist covers start, run-as user, write approvals and model.
  • Runs: see skipped actions, timeouts, event-triggered runs and full errors. Copy, download or expand the output. A failed run keeps its partial output.
  • Triggers: filters are kept on edit and shown. You can test a trigger on a real document, open the run a firing started, and runaway loops are capped at 20 fires per trigger and document per hour. The cap is configurable with fac_trigger_breaker_max_fires_per_hour.
  • Templates: a typed import form with required fields enforced, a summary of what a template needs and how it runs, and templates that create their own trigger on import.
  • An FAC Cloud outage now shows as an outage with retry, not an empty list.

FAC Chat ​

  • Thinking level: choose from Off to Max. The receipt names the level used, and a failing hand-picked model opens the model picker.
  • Files: the model sees every file attached in the conversation on every turn. A send waits for its uploads, attachments survive a reload, and two files with the same name both show.
  • Stop and Continue: Stop is honoured however early it is pressed, and never overwrites text that was already saved. Continue appends to the turn instead of replacing it.
  • Desk widget: rebuilt on FAC Chat's own components. Outage and announcement banners show inside the panel, and typing in it no longer triggers Desk keyboard shortcuts.
  • Quota and billing: quota prompts are now cards and a launcher dot, not dialogs over Desk. Admins are offered plans and credits, and members are asked to contact their admin. The payment tab shows why the last payment failed. The billing form offers every country, UPI Autopay is offered only in India, and the plan refreshes after checkout.
  • Onboarding: email verification resumes instead of asking you to reconnect, and a dead verification link says so and offers a new one.
  • Privacy: every user receives the workspace's memory-consent policy, and the first-run consent switch starts off unless the workspace is Opt-Out.
  • /chat?prompt=… pre-fills a new chat without sending it.

MCP tools ​

  • document_action replaces submit_document and can also cancel and amend.
  • list_documents: pages with offset and next_offset, pages never overlap, and the count works on Frappe v16.
  • generate_report: max_rows and summary_only bound large reports, and the response includes total_count. A prepared report that is still running is reused, and one that completes with zero rows is returned instead of being treated as unfinished and queued again.
  • attach_chat_file attaches a chat upload to a document.
  • Writes: Table MultiSelect rows are written, child DocTypes are routed via their parent, and document_action and create_document stay atomic inside workflows. Every write tool says why a permission was denied, and a non-admin user can create their own ToDo.
  • run_python_code: imports of pre-loaded modules now bind their names, so from collections import Counter and from datetime import datetime work. collections, itertools, functools, heapq, bisect, copy and string are available. Printed output is kept when the code fails.
  • Performance: the tool registry is built in one pass, and skipped entirely for methods that never read it.

Skills ​

  • Six system skills let the assistant audit and configure an ERPNext site through conversation, among them site-health-check (read-only, reported by severity) and guided-setup. They share a plan → confirm → validate → write protocol.
  • The Claude skill-export template is retired.

Credits ​

The run_python_code sandbox escape was reported responsibly by Manhal Muzhir Al-Ghanimy. Thank you.

v3.0.0

2026-09-23

The assistant moves inside your ERP ​

Until now, Frappe Assistant Core was a bridge: it exposed your Frappe data over MCP so an external client like Claude Desktop could reach it. That path is unchanged, still free, and still the default.

What's new is the other half — FAC Chat, a full assistant that lives inside Frappe itself. A widget on every Desk page and a full-screen workspace at /copilot, answering from your own records, inside your own permissions, with every tool call written to the audit log.

And with MCP Connect, it is no longer limited to the tools we ship. Point it at any MCP server — Slack, Linear, a second ERPNext instance — and the assistant works with those alongside your ERP data.

FAC Chat is opt-in and ships disabled. If you use FAC as an MCP server, this release changes nothing about how you work.

Details, plans and sign-up: https://fac-suite.com

New features ​

FAC Chat — a Desk widget and a /copilot workspace. It reads the screen you are on, so "this invoice" or "this customer" means what you would expect. It can draft and submit documents, run reports and update records, always behind a confirmation step. Enable it from the FAC page on the apps screen; the toggle takes effect immediately, with no restart.

MCP Connect — bring your own tools. Connect external MCP servers from FAC Chat → Settings → Connections. Paste an endpoint and FAC checks the URL is well formed, that the server is reachable, and that it genuinely speaks MCP — then handles the sign-in for you, including OAuth dynamic client registration, so there is usually no client ID to create by hand. You see what the server exposes before anything is saved, and you allow or block individual tools per server.

Knowledge Base — upload the documents your business runs on (policies, SOPs, contracts) and ask questions against them. Answers cite the source document and section.

Agents and workflows — describe repetitive work in plain language and FAC builds an agent for it, runnable on a schedule or an event. Runs are inspectable node by node.

Workspace routing rules — route specific work to specific models. A new rule starts in shadow mode: matched and recorded, never applied, so you can see what it would have done before it does it. Every routed turn carries a receipt.

Support, in the product — raise a ticket from chat with screenshots or PDFs attached, read replies inline, and track everything under My Tickets.

Your FAC Connect endpoint, surfaced — the MCP endpoint other clients use to reach this ERP now appears in chat settings, not only in the Desk admin page.

Plus voice input in both the SPA and the widget, and expandable charts and diagrams with PNG export.

Security ​

  • Frappe permissions govern reads; writes to code DocTypes are hard-blocked. Read access is decided by Frappe's own permission model rather than a parallel list, and write attempts against code-bearing DocTypes (Server Script, Client Script and friends) are refused outright regardless of role.
  • FAC Chat runs inside your existing permission model. It can only read what the signed-in user can already read, and every tool action is recorded in the Assistant Audit Log.
  • Chat records are owner-scoped at the DocType level too. Messages, usage logs and preferences were already filtered to the signed-in user by permission hooks; the underlying role grant is now restricted to the record's owner as well, so the two agree without relying on the hooks alone.
  • Carries forward the 2.5.1 fixes, including admin-only publish and share for FAC Skills and its migration patch.

Improvements ​

  • Credits are stated in plain terms. Usage is expressed in credits with a sense of scale, and expiring credits are surfaced on their own rather than buried in a total.
  • An unpaid renewal is visible where you would look — the billing hero, the Users page, the sidebar, and a Pay action on the specific owed invoice, all from one resolver so they cannot disagree. Adding a seat against a frozen billing cycle is now blocked with a stated reason instead of quoting a seat at 0.00 that could not actually be bought.
  • Chat holds up under real use — compose while a response streams, a Stop that genuinely stops, Continue to resume a truncated answer, and pending approvals that survive a dropped connection.
  • Leaner tool schemas. The six largest tool definitions were trimmed; a budget test keeps them that way.
  • Mobile is a real surface — drawer navigation, single-column chat, and reflowed list and settings pages rather than a narrowed desktop layout.
  • Settings reorganised into Personal and Workspace groups, with an explicit unsaved-changes bar.

Fixes ​

  • list_documents count and ordering — the count query no longer fails on a scalar result, and the order_by sentinel is handled correctly.
  • Carries forward the 2.5.1 correctness fixes: submittable DocTypes default to submitted-only, unresolved Link filter values are surfaced on zero-row results, and report filters are validated against each report's own declared contract.

⚠️ Breaking changes ​

Search is consolidated into one tool. search_doctype and search_link are removed; use search_documents, which routes on doctype and purpose. If you have saved prompts, skills or MCP client configurations naming either of the removed tools, update them. The two skills that documented them (search-doctype-usage, search-link-usage) are removed with them. The ChatGPT-compatible search and fetch tools are unaffected.

Minimum Python is now 3.10 (previously 3.8). Frappe v15 and later already require 3.10+, so most sites are unaffected.

Upgrading ​

bash
bench get-app frappe_assistant_core
bench --site <your-site> migrate
bench restart

Take a backup first, as you would for any major version. Four patches run on migrate: recategorize_generate_document, widen_credits_used_to_float, backfill_browser_diagnostics_default and backfill_workflow_trigger_docname.

FAC Chat stays disabled after upgrading. Nothing changes for MCP clients until you turn it on.

Requirements ​

  • Frappe v15 or v16
  • Python 3.10+
  • assistant_runtime_sdk 1.9.0, installed automatically from PyPI
  • Node 22+ — only to build the FAC Chat UI. The assets are built on your instance rather than shipped pre-built, so a bench on an older Node will fail that build step: upgrade Node to 22 and re-run bench build. A site using FAC purely as an MCP server does not need this.
  • A FAC Cloud connection for chat — https://fac-suite.com

Full documentation: https://docs.assistantcore.cloud FAC Chat and FAC Cloud: https://fac-suite.com

v3.0.0-beta.3

pre-release2026-09-18

FAC 3.0.0-beta.3 ​

Third beta of the 3.0 line. The headline is MCP Connect — a guided way to plug external MCP servers into FAC Chat — plus billing visibility for unpaid renewals and a round of stability trimming.

pip/bench will not pick this up automatically — pre-releases are opt-in. Install it explicitly (see Installing the beta below).

MCP Connect: bring your own tools ​

FAC Chat can now reach external MCP servers, not just the built-in toolset — and FAC's own MCP endpoint is finally visible from inside the chat settings instead of only in the Desk admin widget.

A wizard that shows the cost before you pay it ​

Adding a server walks through a guided flow — entry, a preflight check, an auth step (OAuth via Dynamic Client Registration, or manual credentials, with an escape hatch either way) — and ends on a review screen that states plainly what you're about to get: "Adds 32 tools to every conversation." The tool list is what sits at the front of every prompt, so the cost is stated in the unit you actually reason in — tools, not tokens. FAC prices everything in credits and shows token counts nowhere.

Per-tool permissions, not just an on/off switch ​

Each connected server gets its own visibility picker — allow or block individual tools, not just the whole server. Read-only tools default to Always allow, so the common case doesn't need a click.

The connections page, redesigned ​

Rebuilt as a single ruled list instead of a stack of oversized cards, matching the width of every other settings page. A healthy connection is a quiet dot; a broken one raises a strip stating what happened and the one action that fixes it — status only speaks when there's something to say. Your managed FAC-to-your-ERP connection sits apart, visually, from anything you've added yourself, and can't be edited or removed from here.

The pre-filled catalogue of third-party integrations (Composio, Zapier, Pipedream) is gone — every entry opened the same blank form the Add button already does, so it promised a shortcut it didn't deliver.

Billing: an unpaid renewal is visible where you'd look ​

Previously, a stalled renewal was invisible everywhere except one tab nobody opens unless they already suspect a problem — and it wouldn't even show a subscription as past-due, since a stalled renewal freezes the billing cycle without flipping that flag. A tenant could owe real money and see nothing.

The amount owed is now surfaced in the four places that matter: the billing page hero, a persistent notice on the Users page, the sidebar avatar and Settings row, and a direct Pay action on the specific unpaid invoice. All four read from one resolver, so they can't disagree with each other or with what the Pay button actually charges.

Tied to a real fix: admins could previously open the Add seat modal against a frozen billing cycle and see a seat quoted at ₹0.00 — because AR has nothing to price a seat against until the renewal clears. The modal now shows why it's blocked instead of a free seat the next click couldn't actually buy.

Stability and correctness ​

  • The six largest tool schemas are trimmed — one schema alone was 53% of a 9,000-token tool block. A regression test now holds each of the six to a budget, so this doesn't creep back silently.
  • No raw token counts surface anywhere a user can see them — continuing the credit-clarity work from beta.2, this closes the last few spots that still leaked a token number instead of a credit figure.
  • Identity fixes: the session account is now resolved to its actual email before a support ticket or attachment reaches AR, and tenant-owner detection now correctly treats the owner as the login that registered the site, not the address FAC happens to email — both instances of the same docname-vs-email distinction that matters most for the Administrator account.

Carried forward ​

This beta is rebuilt on the current beta line, so it also carries the fixes already shipped there — most importantly two that predate this beta line and must not regress: FAC Skills admin-only publish and share (plus its migration patch retroactively locking down anything published before the fix existed), and list_documents defaulting submittable DocTypes to submitted-only, so cancelled and draft documents never sneak into a monetary total.

Breaking changes ​

None beyond what beta.1 already introduced. This release is additive on top of beta.2.

Upgrading ​

bash
bench get-app frappe_assistant_core --branch beta
bench --site <your-site> migrate
bench restart

Requirements ​

  • Frappe v15 or v16
  • Python 3.10+
  • assistant_runtime_sdk >= 1.9.0 (installed automatically from PyPI)
  • A FAC Cloud connection for chat (register at https://fac-suite.com)

Installing the beta ​

bash
# track the beta line
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch beta

# or pin this exact release
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch v3.0.0-beta.3

main continues to serve the stable v2.5.1 line. Nothing changes for sites that stay on it.

Feedback ​

Built and supported by Promantia.

v3.0.0-beta.2

pre-release2026-09-11

FAC 3.0.0-beta.2 ​

Second beta of the 3.0 line. This release is mostly about FAC Cloud — how credits are explained and spent, self-serve billing, routing control — plus a round of stability and usability fixes across chat, the widget, and mobile.

pip/bench will not pick this up automatically — pre-releases are opt-in. Install it explicitly (see Installing the beta below).

FAC Cloud: credits and routing ​

Say what a credit actually is ​

The usage view now explains credits in plain terms instead of raw token counts — token counts are dropped from the UI and API responses entirely, in favor of a single number with a sense of scale. The usage drill-down shows the real model behind each turn and a per-model delegation breakdown, so a spend spike is traceable to what actually ran.

The credit ledger shows what expires, and when ​

Prepaid credits carry an explicit expiry, shown on its own banner rather than buried in a total. The purchase modal and usage chart were rebuilt around the same ledger data so the number in every view agrees.

Workspace routing rules ​

Admins can now write rules that route specific work to specific models, instead of relying on auto-mode's judgment call every time. A new rule starts in shadow mode — matched and logged, never applied — so its effect is visible before it changes anything; taking it live is one click. Every routed turn carries a receipt end-to-end (SPA, widget, and mobile), shown as an exception-only chip so routing is invisible until it does something worth knowing about.

Self-serve billing ​

  • Payment Method tab with self-serve card update — no more routing card changes through support
  • Team plans are priced and quoted by the seat, including prorated credits on a mid-cycle seat purchase
  • Idle seats are now visible to admins, with a one-click release
  • Payment now always happens on FAC Cloud; the on-site payment gateway is gone

Support tickets, with attachments ​

Raise a ticket from chat with a screenshot or PDF attached, and read replies inline — including attachments the support team sends back. Backed by the SDK's new attachment upload/download proxy (assistant-runtime-sdk 1.7.0).

Stability and usability ​

The widget stops serving stale JS ​

The widget's cache-busting stamp is now a content hash of its own assets, not just the release version — so a change ships immediately instead of waiting for browsers to age out a 12-hour cache. This was a real bug users could hit: an old cached widget silently talking a stale protocol to a current server.

Chat holds up under real use ​

  • Compose while streaming — queue a message instead of waiting for the current response to finish
  • Stop actually stops — a Redis-backed cancel registry propagates Stop to AR instead of just hiding the UI
  • Continue picks up a truncated response instead of losing it
  • HITL recovers from a dropped connection — a pending approval hydrates on reconnect instead of vanishing
  • A notification center (bell + outage/high-priority banners) replaces the old single-banner approach

Settings, reorganized ​

Personal and Workspace settings are now visibly separate groups, with Appearance split out of Profile and a save-bar that actually tells you when there's something unsaved.

Everything else ​

  • Voice input (mic button) in both the SPA and the widget
  • Expandable charts and Mermaid diagrams with PNG export
  • A ledger index for jumping to and pinning specific turns in a long conversation
  • Optional, redacted browser diagnostics attached to a bug report, behind an explicit toggle
  • A shorter onboarding flow that surfaces the Free plan instead of assuming a paid one

Carried forward from v2.5.1 ​

This beta is rebuilt on top of the current beta line, so it also carries everything already shipped there, most importantly two fixes that predate this beta line and must not regress:

  • FAC Skills: admin-only publish and share, plus the migration patch that retroactively locks down any skill published before the fix existed
  • list_documents defaults submittable DocTypes to submitted-only — cancelled and draft documents no longer sneak into a monetary aggregate
  • Report filters are validated against each report's own declared contract, with Select-style options always advertised as an explicit list

Breaking changes ​

None beyond what beta.1 already introduced. This release is additive on top of it.

Upgrading ​

bash
bench get-app frappe_assistant_core --branch beta
bench --site <your-site> migrate
bench restart

Requirements ​

  • Frappe v15 or v16
  • Python 3.10+
  • assistant_runtime_sdk >= 1.7.1 (installed automatically from PyPI)
  • A FAC Cloud connection for chat (register at https://fac-suite.com)

Installing the beta ​

bash
# track the beta line
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch beta

# or pin this exact release
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch v3.0.0-beta.2

main continues to serve the stable v2.5.1 line. Nothing changes for sites that stay on it.

Feedback ​

Built and supported by Promantia.

v3.0.0-beta.1

pre-release2026-09-07

FAC 3.0.0-beta.1 ​

The chat experience moves into Frappe Assistant Core.

Install the app, register the site, and your team gets an AI assistant that works inside ERPNext with the permissions they already have.

This is a beta. It is useful today, and we are releasing it to find the edges we have not hit ourselves. Please open an issue for anything that breaks.

pip/bench will not pick this up automatically — pre-releases are opt-in. Install it explicitly (see Installing the beta below).

What's new ​

FAC Chat, inside your ERP ​

A full chat workspace that understands the screen you are on. Ask about "this invoice" or "this customer" without restating which one you mean.

  • Answers from your ERP records — customers, invoices, stock, projects
  • Ask from any screen — the assistant picks up the document context
  • From answers to action — draft and submit documents, run reports, update records, with a confirmation step before anything is written

Knowledge Base ​

Upload the documents your business actually runs on — policies, SOPs, contracts, manuals — and ask questions against them. Answers cite the source document and section they came from.

Agents ​

Describe repetitive work in plain language and FAC Chat builds an agent for it. Run it on a schedule or on an event.

Model routing ​

Works with leading AI models — Anthropic, OpenAI, Google and AWS Bedrock. Automatic routing sends simple questions to fast models and harder ones to more capable models, with fallback if a provider is unavailable.

Team-level control ​

Per-user usage, credit limits, and spend visibility for admins, with role-based access for everyone else.

Permissions are enforced, not approximated ​

FAC Chat runs inside your existing ERP permission model. It can only read what the signed-in user can read, and every tool action is written to the audit log.

Breaking changes ​

Minimum Python is now 3.10 ​

Previously 3.8. Frappe v15 and later already require 3.10+, so most sites are unaffected.

FAC Cloud registration is required for chat ​

The assistant is powered by FAC Cloud, the hosted AI runtime. The app is open source and installs on your own Frappe/ERPNext site, but chat stays inactive until the site is registered and connected. Everything else in Frappe Assistant Core — the MCP server, tools and skills — continues to work without it.

Includes everything through v2.5.1 ​

This beta is built on top of v2.5.1, so it carries the fixes released there, including the FAC Skills permission fixes (admin-only publish and share) and their remediation patch. Upgrading from 2.5.x does not lose them.

Upgrading ​

bash
bench get-app frappe_assistant_core --branch beta
bench --site <your-site> install-app frappe_assistant_core   # first install only
bench --site <your-site> migrate
bench restart

Four patches run on migrate:

Patch What it does
v3_0.recategorize_generate_document Moves generate_document from read-only to write
v3_0.widen_credits_used_to_float Widens FAC Chat Message.credits_used from Int to Float for fractional credits
v3_0.backfill_browser_diagnostics_default Applies the browser-diagnostics default to the pre-existing settings Single
v3_0.backfill_workflow_trigger_docname Binds workflow triggers to a stable docname instead of the mutable display name

Take a backup before migrating, as you would for any major version.

Requirements ​

  • Frappe v15 or v16
  • Python 3.10+
  • assistant_runtime_sdk >= 1.5.0 (installed automatically from PyPI)
  • A registered FAC Cloud connection for chat

Installing the beta ​

Pre-releases are not installed by default. Point at the branch or the tag explicitly:

bash
# track the beta line
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch beta

# or pin this exact release
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core --branch v3.0.0-beta.1

main continues to serve the stable v2.5.1 line. Nothing changes for sites that stay on it.

Feedback ​

This is a beta and we want the bug reports.

Built and supported by Promantia.

v2.5.1

2026-08-20

Bug Fixes ​

v2.5.0

2026-06-15

Bug Fixes ​

  • build MCP WWW-Authenticate metadata URL from host_name with port (#196) (b739a17)
  • centralize OAuth URL resolution in _get_public_base_url() (a0be84c), closes #156
  • include child table metadata in get_doctype_info (#192) (7d5f724)
  • isolate concurrent MCP tool calls with per-request tool registry (5db3b9e), closes #197
  • make report_requirements filter discovery robust and diagnosable (#203) (051825e)
  • normalize OAuth discovery URLs to use host_name config (72020c0), closes #156
  • prevent list_documents permission leak (d07f696)
  • relax beautifulsoup4 pin to support Frappe v16 (#198) (9813a44)
  • ruff formatter fixes for slice notation and line length (2004eaf)
  • use permission-aware get_list in search tools (#189) (b21ae86)

Features ​

  • advertise MCP tool annotations from FAC tool category (a004e5a)

v2.4.3

2026-05-14

Bug Fixes ​

  • accept JSON-string roles in update_tool_role_access (e8d391c)
  • add blank line after import for ruff formatter (24b990d)
  • add nosemgrep comment for required manual commit (de6b141)
  • audit-log: preserve token-count fields in sanitized output (8b3abba)
  • ci: pin commitlint to v19 and switch to yarn lockfile (91ad1ea)
  • coerce date strings to date objects when appending child table rows (32a467e), closes #168
  • create_document: don't shadow translation function _ in MandatoryError handler (e7d2f8d)
  • create_document: drop pre-flight reqd check, defer to Frappe validate() (472699a), closes #165
  • don't shadow translation function _ in MandatoryError handler (f4b569c)
  • drop pre-flight reqd check, defer to Frappe validate() (#165 follow-up) (df83a13)
  • format warnings.append per linter requirements (614c4b1)
  • handle HRMS Skill schema without skill_name column (d52f742)
  • handle HRMS Skill schema without skill_name column (5b9f2e0)
  • loosen chardet constraint to resolve conflict with Frappe 15.107+ fixes #176 (3c63675)
  • move allow_on_submit check and fix formatting (2da4746)
  • ocr: add tesseract as an OCR backend option (f7d7200), closes #99
  • pass user_role to filter_sensitive_fields in chatgpt_fetch (10495c1)
  • pass user_role to filter_sensitive_fields in chatgpt_fetch (a7a24a6)
  • perf: drop dead wildcard doc_events that fired on every bench-wide save (3480ed2)
  • preserve token-count fields in sanitized output (37f687b)
  • rename current_docstatus_check to current_docstatus and fix line length (9141112)
  • security: restrict Prompt Category read from "All" to "Assistant User" (910dcb0)
  • security: sandbox Jinja env to prevent SSTI in prompt templates (3c1768a)
  • support Allow on Submit fields in update_document (55d189e), closes #179
  • support child-table updates; reject direct child-doctype calls (d036e30)
  • update_document: support child-table updates and reject direct child-doctype calls (a6a42bd), closes #168
  • updating the code based on linters (a5bee9b)
  • validate required fields against populated doc in create_document (67fbe55)
  • warn on silent field overrides in create_document (d01ded5), closes #181

v2.4.2

2026-05-07

Bug Fixes ​

  • accept JSON-string roles in update_tool_role_access (e99eff5)
  • audit-log: preserve token-count fields in sanitized output (fbcce43)
  • ci: pin commitlint to v19 and switch to yarn lockfile (f902465)
  • create_document: don't shadow translation function _ in MandatoryError handler (55f7f7d)
  • create_document: drop pre-flight reqd check, defer to Frappe validate() (edaddb4), closes #165
  • handle HRMS Skill schema without skill_name column (8529b4d)
  • pass user_role to filter_sensitive_fields in chatgpt_fetch (8dbb963)
  • update_document: support child-table updates and reject direct child-doctype calls (b99c0bb), closes #168
  • validate required fields against populated doc in create_document (022e9b4)

v2.4.1

2026-04-23

Bug Fixes ​

  • repair HRMS Skill link corruption from v2.4.0 rename patch (4f043ac)
  • repair HRMS Skill link corruption from v2.4.0 rename patch (#153) (973c2e7)

v2.4.0

2026-04-17

Bug Fixes ​

  • drop unused visualization libs from run_python_code sandbox (#146) (6a002da)
  • enforce parent document permission check in extract_file_content (bd88d75), closes #126
  • ignore two historical squash-merge commits in commitlint (#148) (b89ac49), closes #143 #145
  • isolate code execution in subprocess to prevent worker crashes (#142) (5d0e956)
  • remove dead create_visualization tool with SQL injection vulnerability (#132) (1074878)
  • remove unprotected whitelist decorators from duplicate config endpoints (#133) (a46d463)
  • restrict usage statistics to assistant admins (#140) (56315ed)
  • skip signal-based timeout in worker threads (#122) (a2fbe72), closes #118 #121 #118

Features ​

  • add get_pending_approvals tool for workflow action discovery (#127) (de14958)
  • add support for image data in tool responses (#123) (e73e929)
  • Skills subsystem — FAC Skill DocType, admin tabs, external app registration (#145) (720d560), closes #118 #121 #118

v2.3.4

2026-04-07

Bug Fixes ​

  • prevent OAuth Basic auth monkey-patch from persisting across worker requests (#131) (5c22232), closes #129

v2.3.3

2026-03-19

Bug Fixes ​

  • make PaddleOCR dependencies optional for Frappe v16 (#118) (#121) (a2f493e)

v2.3.2

2026-03-18

🆕 New — OCR & Document Extraction ​

FAC now supports extracting text from images and scanned PDFs directly through your AI assistant. Two backends are available out of the box:

  • PaddleOCR integration — high-accuracy text extraction using PaddleOCR with support for multiple languages. Runs in a subprocess with configurable memory limits and timeouts to keep your server stable.
  • Vision model support — use Ollama-based vision models (e.g., deepseek-ocr:latest) as an alternative OCR backend for more complex document understanding.
  • Configurable OCR settings — choose your preferred backend, language, timeout, and memory limits directly from Assistant Core Settings. No config files to edit.
  • Model warmup — optional background warmup for PaddleOCR models so the first extraction request is fast.

🚀 Improvements ​

  • Audit log cleanup — automatic retention policy (default 180 days) keeps your audit logs manageable without manual intervention. Configure the retention period in Assistant Core Settings to match your compliance requirements. Cleanup runs daily via a scheduled job.
  • Better report feedback — report tools now provide clear guidance when used incorrectly, instead of failing silently. Default filters are also included in generate_report responses so the AI knows what parameters were applied.
  • OAuth localhost support — native apps like OpenCode and MCP Inspector can now register with HTTP localhost redirect URIs without errors. This follows RFC 8252 which explicitly allows HTTP for loopback connections since the traffic never leaves your machine.
  • MCP 2025-06-18 spec — updated to the latest MCP authentication specification for better compatibility with newer MCP clients.
  • Code execution limits — the run_python_code sandbox now enforces configurable timeout, memory, CPU, and recursion limits to prevent runaway scripts. All limits are configurable from Assistant Core Settings.
  • Settings defaults — all settings now correctly apply their default values on fresh installs and upgrades. No more missing defaults after bench migrate.

🔒 Security Fixes ​

  • Fixed unauthorized access to protected API endpoints — non-authenticated users were able to reach endpoints that should have required authentication (#108)
  • Fixed sensitive credential values appearing in server logs — replaced with non-sensitive status messages so your logs are safe to share during debugging (#114)
  • Removed unused API endpoints (handle_assistant_request, force_test_logging, log_assistant_connection, log_assistant_audit) that were unnecessarily exposed and could be called by any authenticated user (#111, #105)
  • Added regression tests for admin API permissions to catch authorization issues early in CI

🐛 Bug Fixes ​

  • Fixed duplicate "Security" tabs appearing in Assistant Core Settings
  • Fixed PaddleOCR 3.x API incompatibility — updated constructor and call patterns to work with the latest PaddleOCR release (#107)
  • Fixed overly aggressive import restrictions in the Python sandbox that broke numpy/pandas internal lazy imports

🧹 Housekeeping ​

  • Removed ~1,150 lines of dead code — unused streaming manager, response builder, cache utilities, dashboard helpers, and stale constant definitions
  • Added code execution security documentation

🔄 Migration ​

After upgrading to v2.3.2, run:

bash
bench --site your-site migrate

This will:

  • Apply default values for all settings fields
  • Update MCP protocol version to 2025-06-18 spec
  • Set up audit log retention (180 days default)

🙏 Contributors ​

A big thank you to @renanwilliam for his first contribution to FAC — fixing OAuth Dynamic Client Registration with HTTP localhost URIs for native apps (#104). Welcome to the project! 🎉

Closed Issues ​

  • #103 — OAuth DCR fails with HTTP localhost redirect URIs
  • #105 — Additional endpoints need authorization checks
  • #107 — PaddleOCR 3.x compatibility
  • #108 — Non-authenticated users accessing protected endpoints
  • #109 — Auth-sensitive information leaking into logs
  • #111 — Any authenticated user can clear caches
  • #114 — Credential values in logs
  • #115 — Audit log cleanup

v2.3.1

2026-02-06

Database-backed plugin & tool management with Frappe V16 support

What's New ​

This release introduces a robust, database-backed system for managing plugin and tool enable/disable states and access control. It replaces the previous JSON-based approach with new DocTypes for granular, atomic, and multi-worker-safe configuration. Frappe V16 is now officially supported.

Plugin & Tool Management Architecture ​

FAC Plugin Configuration DocType ​

A new DocType for atomic, database-backed plugin enable/disable control with:

  • Audit trail for every state change
  • Automatic cache invalidation for multi-worker consistency
  • API functions for toggling and querying plugin states programmatically

FAC Tool Configuration DocType ​

A new DocType for per-tool configuration and access control with:

  • Enable/disable toggle for individual tools
  • Category assignment (read_only, write, read_write, privileged)
  • Role-based access control via FAC Tool Role Access child table
  • Automatic tool category detection via AST parsing of tool source code

Why This Matters ​

Before (JSON) After (DocType)
File-based state, prone to corruption Atomic database writes
No change history Full audit trail with timestamps and users
Stale reads across workers Cache invalidation ensures consistency
Race conditions under load Database locks prevent conflicts
File I/O bottleneck Scales with your database

Frappe V16 Support ​

  • Official support for Frappe V16 alongside V15
  • Conditional OAuth settings UI based on Frappe version
  • Full backward compatibility with V15 installations

Documentation Updates ​

  • Updated architecture docs describing the new DocType-based configuration system
  • Administrator guide for tool and plugin management
  • Developer documentation for automatic tool category detection with examples and best practices
  • Updated main documentation index for easier navigation

Other Improvements ​

  • Copyright and license headers added to new and updated modules
  • Improved state persistence flow: UI → API → DocType → Cache Invalidation → Consistent reads

Upgrade Guide ​

bash
cd apps/frappe_assistant_core
git pull
bench --site your-site migrate

Migration will automatically:

  • Create FAC Plugin Configuration records for existing plugins
  • Create FAC Tool Configuration records for registered tools
  • Auto-detect tool categories via AST parsing

Compatibility ​

Frappe Version Supported
V15 Yes
V16 Yes (new)
V14 and below No

Python: >= 3.8

Full Changelog ​

See CHANGELOG.md for the complete list of changes.

Full Diff: v2.3.0...v2.3.1

v2.3.0

2026-01-09

Frappe Assistant Core v2.3.0 ​

Highlights ​

Prompt Templates System - This release introduces a major new feature: database-driven prompt templates with full MCP protocol support. Domain experts can now create reusable, parameterized prompts that users can customize and execute via AI clients.

Major Feature - Prompt Templates System ​

MCP Prompts Support ​

FAC now supports the MCP prompts/list and prompts/get protocol methods, enabling "Prompt Engineering as a Service":

  • Full MCP prompts protocol support (prompts/list, prompts/get)
  • Database-driven prompt templates replacing hardcoded prompts
  • Template rendering with Jinja2, Format String, and Raw engines
  • Usage analytics tracking (use_count, last_used)

New DocTypes ​

DocType Purpose
Prompt Template Main template with content, arguments, and metadata
Prompt Template Argument Child table defining configurable parameters
Prompt Category Hierarchical tree structure for organization

Features ​

  • Template Content: Jinja2 templates with {{ placeholders }} for dynamic content
  • Configurable Arguments: Define parameters with types (string, number, boolean, select, multiselect)
  • Argument Validation: Required fields, regex patterns, allowed values, min/max length
  • Default Values: Pre-populate optional arguments
  • Live Preview: Test template rendering before publishing

Access Control & Sharing ​

  • Visibility Levels: Private (owner only), Shared (specific roles), Public (all users)
  • Role-Based Sharing: Share prompts with specific Frappe roles
  • System Templates: Protected templates installed via migration (cannot be deleted)
  • Permission Filtering: MCP returns only prompts accessible to current user

Versioning & History ​

  • Automatic version number increment on significant changes
  • Full change history using Frappe's track_changes
  • Rollback to any previous version
  • Duplicate system/public templates for customization

Pre-built System Templates ​

  • manufacturing_analysis - Manufacturing & production analysis
  • sales_analysis - Sales performance and trends
  • purchase_analysis - Procurement and supplier analysis
  • hr_analysis - HR metrics and workforce analysis
  • crm_analysis - Customer relationship analysis
  • doctype_documentation - DocType documentation generator
  • data_quality_audit - Data quality and integrity audits

Bug Fixes ​

OAuth Token Timezone Fix (#83) ​

  • Fixed timezone mismatch in OAuth token expiration validation
  • Changed from datetime.datetime.now() to Frappe's now_datetime() for timezone-aware comparisons
  • Users in non-UTC timezones no longer experience premature token expiration

CI/CD Pipeline Fixes ​

  • Fixed CI failing due to Python version incompatibility with Frappe 16 dev branch
  • Changed bench init to explicitly use --frappe-branch version-15 for stable builds
  • Upgraded CI Python version from 3.10 to 3.12

Code Quality - cur_frm Deprecation Fixes ​

  • Fixed semgrep frappe-cur-frm-usage violations in prompt_template.js
  • Replaced deprecated cur_frm usage with proper Frappe patterns

UI/UX Improvements ​

Dark Theme Support ​

  • FAC Admin Page: Fixed MCP Endpoint URL visibility, toggle switches, tool badges, and table cells
  • Assistant Core Settings: Updated alert boxes, plugin cards, form controls, and search inputs to use CSS variables

Documentation ​

  • Added comprehensive Prompt Templates User Guide
  • Updated MCP StreamableHTTP Guide with timezone-aware token validation example
  • Updated Technical Documentation with correct now_datetime() usage

Migration Notes ​

After upgrading to v2.3.0, run:

bash
bench --site your-site migrate

This will install:

  • System prompt categories
  • System prompt templates
  • Required database schema changes

Full Changelog ​

See CHANGELOG.md for complete details.

Contributors: @buildswithpaul

New Contributors

@Alababdiy made their first contribution in #84

Full Changelog: https://github.com/buildswithpaul/Frappe_Assistant_Core/compare/v2.2.2...v2.3.0

v2.2.2

2025-12-03

🏢 Repository Migration & Rebranding ​

GitHub Repository Update ​

  • Migrated repository from clinu/Frappe_Assistant_Core to buildswithpaul/Frappe_Assistant_Core
  • Updated all documentation links, URLs, and references across the project
  • Updated manifest.json, README.md, BUILD.md, and configuration files
  • Maintained backwards compatibility - existing installations continue to work

🚀 Enhanced ​

OAuth 2.0 Client Registration Enhancements ​

  • Fixed dynamic client registration to always return client_secret in response
  • Added support for public clients that receive secrets but use token_endpoint_auth_method: "none"
  • Enhanced registration response to include all optional RFC 7591 metadata fields:
    • client_uri - Client homepage URL
    • logo_uri - Client logo URL
    • scope - Requested scopes
    • contacts - Client contact information
    • tos_uri - Terms of Service URL
    • policy_uri - Privacy Policy URL
    • software_id - Client software identifier
    • software_version - Client software version
  • Improved MCP Inspector compatibility with complete registration responses
  • Benefits:
    • Full RFC 7591 compliance
    • Better client identification and metadata
    • Improved debugging and client management

OAuth Discovery API Updates ​

  • Updated OpenID Configuration endpoint to use get_openid_configuration from Frappe
  • Improved compatibility with latest Frappe OAuth2 API changes
  • Maintained backward compatibility with Frappe v15 and v16

Manifest & Tool Configuration Improvements ​

  • Refactored tools array in manifest.json with updated names and descriptions
  • Added new tools: delete_document, submit_document
  • Reorganized tool descriptions for consistency and improved user experience
  • Improved tool ordering for better discoverability
  • Updated runtime specification from runtime to runtimes for future extensibility
  • Clarified Python version requirements (>=3.8,<4.0)

Documentation Improvements ​

  • Enhanced Getting Started guide with UI-based connector setup for Claude Desktop
  • Added ChatGPT integration section with complete setup instructions
  • Added comparison table for different AI connection options
  • Improved OAuth setup instructions with both UI and manual configuration methods
  • Updated all repository references to new GitHub location
  • Added tips and best practices for easier onboarding
  • Benefits:
    • Much easier setup with UI-based configuration (no JSON editing)
    • Support for both Claude Desktop and ChatGPT clearly documented
    • Better user guidance with comparison table and recommendations

🔧 Changed ​

API Endpoint Updates ​

  • Updated Claude Desktop extension server bridge API endpoint
  • Changed from: /api/method/frappe_assistant_core.api.assistant_api.handle_assistant_request
  • Changed to: /api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp
  • Note: This change is for internal bridge configuration; external MCP endpoint remains unchanged

v2.2.1

2025-11-24

🚀 Enhanced ​

Prepared Report Polling Support - Issue 52 ​

  • Implemented automatic polling logic for prepared (background) reports
  • Added exponential backoff strategy (2→4→6→9→13 seconds) to efficiently wait for report completion
  • Enabled seamless UX where AI gets report data without interrupting conversation flow
  • Eliminated manual retry requests - system automatically polls until report is ready
  • Added comprehensive error handling for timeouts, failures, and edge cases
  • Maintained backward compatibility - cached reports still return immediately
  • Benefits:
    • Users no longer need to manually retry failed reports
    • Reduced database load with smart exponential backoff
    • Production-ready with graceful timeout handling (max 30 seconds)
    • Transparent progress tracking via logging

Multi-Tool Orchestration for run_python_code ​

  • Implemented Tools API for calling other tools inside Python sandbox
  • Achieved 80-95% token savings for data analysis workflows by processing data in sandbox instead of passing through LLM context
  • Added tools.get_documents() and tools.generate_report() methods for orchestrated data fetching
  • Enabled complex analysis patterns: fetch data inside code, process with pandas/numpy, return only insights to LLM
  • Updated tool description to make orchestration the PRIMARY recommended approach
  • Example: Instead of calling list_documents separately (sends 100 invoices to LLM), write Python code that calls tools.get_documents() internally (only analysis results go to LLM)

Authentication & Security Enhancements ​

  • Refactored MCP endpoint authentication to support both OAuth 2.0 Bearer tokens and API key/secret methods
  • Added _authenticate_mcp_request() function with clear separation of authentication logic
  • Enabled STDIO clients (like bridge implementations) to authenticate via API key/secret: Authorization: token <api_key>:<api_secret>
  • Improved error handling for unauthorized requests with proper 401 responses and WWW-Authenticate headers
  • Enhanced OAuth discovery endpoint to always bypass cache for fresh configuration
  • Fixed OAuth scope parsing to handle both space-separated and newline-separated lists, preventing duplicates

Plugin & Tool Registry Improvements ​

  • Fixed custom tools appearing in tools/list API even when custom_tools plugin was disabled
  • Added plugin state check in _get_external_tools() to respect disabled state for hook-registered tools
  • Implemented comprehensive cache clearing after plugin toggle (plugin manager cache, tool registry cache)
  • Improved plugin toggle UX with disabled state during API calls and error recovery

Data Compatibility Fixes ​

  • Fixed frappe._dict to plain dict conversion for pandas DataFrame compatibility
  • Resolved "invalid array_struct" errors when using pandas with tool data
  • Updated tools.get_documents() and tools.get_document() to return plain Python dicts
  • Updated report_tools.py to convert report data rows to plain dicts
  • Added comprehensive null value handling guidance in tool descriptions

MCP Server Cleanup ​

  • Removed unused @mcp.tool decorator method (~95 lines of dead code)
  • Removed _generate_input_schema() and _get_json_type() helper methods
  • Clarified that BaseTool is the only supported tool development pattern
  • Updated MCPServer class documentation with correct usage examples
  • Removed unused imports (Callable, Parameter, getdoc, signature)

Admin Page & UX Improvements ​

  • Improved plugin toggle to disable checkbox during API calls
  • Added state reset on toggle errors to prevent UI inconsistencies
  • Enhanced endpoint URL display with fallback handling
  • Fixed AssistantCoreSettings to populate endpoint URLs on load and before save
  • Ensured MCP and OAuth discovery URLs are always up-to-date

🐛 Bug Fixes ​

  • Fixed custom_tools plugin state not being respected for external tools from hooks
  • Fixed pandas DataFrame creation failures with frappe._dict objects
  • Fixed null value formatting errors in run_python_code examples
  • Fixed endpoint URL population timing in settings DocType
  • Fixed plugin cache not refreshing after state changes
  • Fixed prepared (background) reports failing with "Report is being prepared" error - now polls automatically until ready

📚 Documentation ​

  • Updated run_python_code tool description with orchestration patterns and best practices
  • Added clear CORRECT vs INCORRECT usage examples
  • Added data handling best practices section with null value handling
  • Updated MCPServer class docstring to reflect BaseTool-only approach
  • Improved code comments explaining authentication flow and data conversion

🔧 Technical Improvements ​

  • Simplified authentication code structure with dedicated helper function
  • Improved error messages for authentication failures
  • Enhanced logging for plugin state changes and tool discovery
  • Optimized tool registry to skip external tool loading when plugin disabled

v2.2.0

2025-10-14

Release Date: October 13, 2025

🎯 What's New ​

Frappe Assistant Core has been completely rebuilt with StreamableHTTP transport and OAuth 2.0 authentication, making it compatible with modern MCP clients including Claude Web and browser-based tools.

Key Highlights ​

✅ OAuth 2.0 Security - Industry-standard authentication replacing API keys ✅ Web Client Support - Works with Claude Web, MCP Inspector, and browser tools ✅ Simpler Deployment - HTTP endpoint instead of subprocess management ✅ Auto-Discovery - Clients discover endpoints automatically via .well-known ✅ Better UX - Zero manual configuration after installation

🔄 Breaking Changes ​

⚠️ STDIO bridge is going to get deprecated - Migrate to StreamableHTTP for continued support

What Changed:

  • Transport: STDIO subprocess → HTTP POST requests
  • Authentication: API keys → OAuth 2.0 Bearer tokens
  • Configuration: Environment variables → OAuth discovery

Migration: See Migration Guide

🚀 Getting Started ​

For New Users ​

  1. Install Frappe Assistant Core
shell
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site your-site install-app frappe_assistant_core

  1. Get Your MCP Endpoint

    • Go to Desk → Tools → FAC Admin
    • Copy the MCP endpoint URL shown

  2. Connect Your LLM

    • Go to Connectors → Add new connector → Add → Connect

  3. Authenticate - Your browser will open for OAuth authorization

That's it! Start using Frappe tools in your AI assistant.

👉 Detailed Guide: See Getting Started

📦 What's Included ​

OAuth 2.0 Implementation ​

  • RFC 7591 - Dynamic Client Registration
  • RFC 8414 - Authorization Server Metadata
  • RFC 9728 - Protected Resource Metadata
  • RFC 7636 - PKCE (Proof Key for Code Exchange)
  • Automatic token refresh
  • CORS support for public clients

Custom FAC MCP Server ​

  • Optimized for Frappe data types (datetime, Decimal)
  • No Pydantic dependency (lighter footprint)
  • Full error tracebacks for debugging
  • Deep Frappe integration (permissions, sessions, ORM)

UX Improvements ​

  • FAC Admin Page - View MCP endpoint and manage plugins
  • Default-Enabled Access - Users ready immediately after install
  • Mermaid Diagrams - All architecture docs now GitHub-compatible
  • LLM-Specific Guides - Instructions for Claude, ChatGPT, Claude Web

🐛 Bug Fixes ​

  • Fixed CORS headers for OPTIONS preflight requests
  • Fixed plugin toggle using IDs instead of display names
  • Fixed plugin state persistence across refreshes
  • Fixed missing patch files during migration
  • Fixed 401/417 HTTP errors with proper method handling

🙏 Credits & Acknowledgments ​

This release was inspired by and builds upon excellent work from the Frappe community:

Frappe Framework v16 ​

The OAuth implementation in Frappe Assistant Core was significantly inspired by the OAuth improvements introduced in Frappe Framework v16. Special thanks to the Frappe core team for:

  • Modernizing OAuth architecture
  • Implementing frappe.local.allow_cors for v16 CORS handling
  • Setting the foundation for better authentication standards

We've implemented dual compatibility to ensure smooth upgrades.

frappe-mcp by Frappe ​

Valuable insights were drawn from frappe-mcp by Frappe, particularly:

  • MCP StreamableHTTP transport patterns
  • OAuth integration approaches for Frappe
  • Best practices for MCP protocol implementation

Both projects demonstrate the power of the Frappe ecosystem and community-driven innovation.

📊 Architecture Comparison ​

Feature Before (STDIO) After (StreamableHTTP)
Transport stdin/stdout subprocess HTTP POST requests
Authentication API Key in env vars OAuth 2.0 Bearer tokens
Client Support Subprocess-capable only Any HTTP-capable client
Web Compatibility ❌ No ✅ Yes
Token Management Static keys Auto-refresh tokens
Discovery Manual config Auto via .well-known

📚 Documentation ​

🔮 What's Next ​

We're committed to continuous improvement:

  • Performance optimization - Faster tool execution
  • Better monitoring - Admin dashboard improvements
  • More integrations - Additional MCP client support

🤝 Support & Community ​

📄 License ​

AGPL-3.0 License - See LICENSE file for details

Upgrade today and experience the future of Frappe AI integration! 🎉

v2.1.1

2025-09-22

Released: September 2025

What's New ​

CI/CD Pipeline Added proper GitHub Actions workflows for automated testing and linting.

SSE Bridge Improvements

  • New admin dashboard with real-time status monitoring
  • One-click start/stop controls
  • Better error handling when dependencies are missing

Better Tool Error Handling Improved error messages and logging in tool execution. You'll now get clearer feedback when something goes wrong instead of cryptic errors.

Data Model Updates

  • Cleaned up the Assistant Audit Log fields
  • Migrated from Connection Log to audit-based activity tracking
  • Better performance for usage statistics

Bug Fixes ​

  • Fixed SSE bridge startup failures
  • Resolved JSON parsing errors in the frontend
  • Better process management with proper PID tracking
  • Fixed field type inconsistencies in audit logs

Breaking Changes ​

  • SSE bridge now uses dedicated API endpoints instead of direct document methods
  • Connection ID format changed from session_id to cid parameter
  • Some environment variable names for SSE bridge have changed

Migration ​

bash
# Update the app
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site [site-name] migrate && bench setup requirements
bench restart

Installation ​

bash
bench get-app frappe_assistant_core https://github.com/buildswithpaul/Frappe_Assistant_Core.git
bench install-app frappe_assistant_core

Note: The biggest change is the improved SSE bridge reliability. If you were having connection issues before, this release should fix most of them.

v2.1.0

2025-08-29

Major Performance & Feature Release - August 2025

What's New ​

📄 File Processing & Data Science Plugin ​

  • New Tool: extract_file_content - Extract text from PDF, images (OCR), Excel, and Word documents
  • LLM-Optimized: Content formatted for AI analysis with structure preservation

⚙️ Admin Interface Improvements ​

  • Revamped UI: Cleaner interface for Assistant Admin page and settings
  • Real-time Status: Live plugin monitoring and configuration validation

📊 Enhanced Reporting Tools ​

  • Smart Discovery: Improved report finding and parameter detection
  • Better Performance: Faster report loading and execution

⚡ Performance & Concurrency ​

  • Thread Pool: Multi-threaded request processing in frappe_assistant_stdio_bridge.py
  • Optimized Timeouts: Reduced from 30s to 5s for Claude compatibility
  • Default URL: Changed to http://localhost:8000 for local development

Technical Changes ​

Bridge Improvements ​

  • Thread pool architecture with ThreadPoolExecutor(max_workers=4)
  • Explicit timeout error handling
  • Enhanced connection management

Configuration Updates ​

  • Updated manifest.json to version 2.1.0
  • Boolean controls for debug mode
  • Enhanced field validation
  • Python runtime requirements specified

Bug Fixes ​

  • Fixed thread safety issues in concurrent operations
  • Resolved memory leaks in long-running processes
  • Improved timeout handling consistency
  • Enhanced plugin state persistence

Upgrade Instructions ​

bash
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site [site-name] migrate && bench setup requirements
bench restart

Fully backward compatible - No breaking changes.

Support ​

v2.0.3

2025-08-07

Release Date: 08 August 2025
Version: 2.0.3
Security Focus: Enterprise-grade security enhancements and tool improvements

🔒 Major Security Enhancements ​

Python Code Execution Security ​

  • 🛡️ Read-Only Database Wrapper: Implemented comprehensive read-only database access preventing all dangerous SQL operations (DELETE, UPDATE, INSERT, DROP, ALTER, CREATE, TRUNCATE)
  • 👤 Secure User Context Management: Added proper user context handling with automatic rollback and audit trails
  • 🔍 Advanced Code Security Scanning: Enhanced detection of dangerous operations including SQL injection patterns, file system access, and network operations
  • 📝 System Manager Role Enforcement: Restricted code execution to users with System Manager privileges
  • 🚫 Import Statement Protection: Comprehensive blocking of dangerous imports while allowing safe data science libraries

Unicode & Data Handling ​

  • ✨ Unicode Sanitization: Fixed surrogate character errors that caused encoding failures during code execution
  • 🧹 Variable Output Filtering: Resolved verbose output issue by excluding pre-loaded libraries from response variables
  • 📊 DataFrame Compatibility: Improved data handling to prevent invalid __array_struct__ errors in pandas operations

🔧 Tool Improvements & Bug Fixes ​

Report Tools Enhancement ​

  • 📈 Better Error Messages: Updated report tool descriptions to clearly indicate mandatory filters for Sales Analytics and other reports
  • 🎯 Improved Tool Descriptions: Enhanced guidance for tools requiring specific parameters like doc_type and tree_type

Document Management ​

  • 🗑️ Delete Document Tool: Enhanced error handling with specific categorization for permission errors, dependency issues, and validation failures
  • 💬 Silent Failure Fix: Resolved issue where delete operations failed without meaningful error messages
  • 🔄 Better Exception Handling: Added granular error handling with fallback messages for all edge cases

🏗️ Architecture & Refactoring ​

Plugin Cleanup ​

  • 🧹 Removed Unused Components: Eliminated WebSocket and batch processing plugins that were not in active use
  • 📋 Configuration Cleanup: Updated all references and configuration files to remove deprecated components
  • ⚡ Performance Optimization: Streamlined codebase by removing unnecessary dependencies

Security Infrastructure ​

  • 🔐 ReadOnlyDatabase Class: New security wrapper that validates and blocks dangerous SQL operations
  • 👥 User Context Management: Secure context managers with proper session handling and restoration
  • 📊 Audit Trail System: Comprehensive logging of code execution with user attribution and execution tracking

📱 Client Integration Updates ​

Manifest Synchronization ​

  • ✅ Accurate Tool Names: Updated Claude Desktop manifest.json with correct tool names matching actual implementation
  • 📋 Complete Tool List: Added missing tools like delete_document, submit_document, and dashboard creation tools
  • 🎯 Better Descriptions: Improved tool descriptions for better LLM understanding and usage

🚀 Technical Improvements ​

Code Quality ​

  • 🔍 Enhanced Error Handling: Comprehensive error catching with meaningful messages and fallback handling
  • 📝 Detailed Logging: Improved logging for security violations, execution tracking, and debugging
  • 🧪 Security Testing: Built-in security test functions for validation of protective measures

Performance ​

  • ⚡ Optimized Execution Environment: Streamlined setup of secure execution contexts
  • 🎯 Efficient Variable Extraction: Smart filtering to reduce response payload size
  • 📊 Better Data Serialization: Improved handling of complex data types in variable returns

🛡️ Security Features Summary ​

Feature Description Status
Read-Only Database Blocks all write operations ✅ Implemented
User Context Security Proper session management ✅ Implemented
Code Scanning Detects dangerous patterns ✅ Implemented
Unicode Sanitization Handles encoding errors ✅ Implemented
Import Protection Blocks dangerous imports ✅ Implemented
Audit Logging Tracks all executions ✅ Implemented
Role-Based Access System Manager required ✅ Implemented

🔧 Migration Notes ​

For Existing Installations ​

  1. Restart Required: After upgrading, restart your Frappe bench to apply all changes

    bash
    bench restart

  2. Permission Check: Ensure users who need code execution have System Manager role

  3. Client Update: Update Claude Desktop extension to benefit from improved tool manifest

Breaking Changes ​

  • Code Execution Access: Now requires System Manager role (previously available to all users)
  • Database Operations: Direct database write operations through code execution are now blocked
  • Plugin Removal: WebSocket and batch processing plugins have been removed

🐛 Bug Fixes ​

  • Fixed silent failures in delete_document tool
  • Resolved Unicode encoding errors in code execution
  • Fixed verbose output including all pre-loaded libraries
  • Corrected manifest.json tool name mismatches
  • Eliminated data_query not defined errors
  • Fixed function returning None instead of results

🎯 Known Issues Resolved ​

  1. "NoneType object has no attribute 'startswith'" - Fixed in report tools
  2. "invalid array_struct" - Improved data handling guidance
  3. "data_query not defined" - Removed misplaced code references
  4. Silent delete failures - Added comprehensive error reporting
  5. Verbose library output - Filtered pre-loaded libraries from responses

📈 What's Next ​

  • Enhanced visualization capabilities
  • Advanced workflow automation
  • Improved dashboard creation tools
  • Extended security monitoring
  • Performance optimizations

🤝 Contributing ​

For bug reports, feature requests, and contributions, please visit:

📧 Support ​

For support and questions:

⚡ Upgrade to v2.0.3 today for enhanced security and improved functionality!

This release focuses on enterprise-grade security while maintaining backward compatibility for core functionality.

v2.0.2

2025-07-28

What's Changed ​

Full Changelog: https://github.com/buildswithpaul/Frappe_Assistant_Core/compare/v2.0.1...v2.0.2

v2.0.1

2025-07-26

Release Date: July 26, 2025
Version: 2.0.1
Type: Major Bug Fixes & Tool Improvements

🎯 Overview ​

Version 2.0.1 is a significant maintenance release that addresses critical issues in document creation, dashboard chart functionality, and custom tool discovery. This release dramatically improves the reliability and usability of AI assistant tools for Frappe Framework.

🚀 Major Improvements ​

📋 Document Creation Tool Overhaul ​

Problem Solved: The create_document tool frequently failed when creating documents with child tables (Purchase Orders, Sales Invoices, BOMs), causing LLMs to fall back to less reliable methods.

Key Fixes:

  • ✅ Fixed Child Table Handling: Proper doc.append() usage instead of naive setattr()
  • ✅ Automatic Field Validation: Pre-validates required fields before creation attempts
  • ✅ Enhanced Error Messages: Specific guidance for different error types with actionable suggestions
  • ✅ Validate-Only Mode: Test document structure before actual creation
  • ✅ Comprehensive Examples: Updated tool descriptions with proper child table formatting

Impact: Document creation success rate increased from ~60% to ~95% for complex DocTypes.

📊 Dashboard Chart System Rebuild ​

Problem Solved: Dashboard charts were created but failed at runtime with empty "Time Series Based On" and "Value Based On" fields, causing blank charts in dashboard view.

Root Cause: Incorrect field mapping between tool parameters and Frappe's Dashboard Chart DocType structure.

Complete Fix:

  • ✅ Correct Field Mapping:
    • based_on = Time Series Based On (date field)
    • timeseries = Time Series flag (boolean)
    • group_by_based_on = Group By Based On (grouping field)
    • value_based_on = Value Based On (aggregation field)
  • ✅ Filter Format Conversion: Proper conversion from dict to Frappe's list format
  • ✅ Smart Field Detection: Auto-detects appropriate date and grouping fields per DocType
  • ✅ Comprehensive Validation: Pre-validates chart configuration before creation
  • ✅ Runtime Testing: Charts are tested for functionality before being saved

Impact: Charts now work immediately in dashboard view with proper data visualization.

🔧 Custom Tool Discovery Enhancement ​

Problem Solved: Custom tools from external Frappe apps were not being properly discovered through the hooks system.

Fix: Enhanced tool registry to properly scan and load tools from assistant_tools hook in external apps.

Impact: Enables seamless integration of custom business-specific tools from any Frappe app.

🐛 Critical Bug Fixes ​

Document Creation Issues ​

  • Fixed: 'dict' object has no attribute 'is_new' error in child table creation
  • Fixed: Missing required field validation causing creation failures
  • Fixed: Poor error messages that didn't guide users to solutions

Dashboard Chart Issues ​

  • Fixed: TypeError: 'NoneType' object is not callable in chart data retrieval
  • Fixed: Unknown column 'tabItem.posting_date' in 'WHERE' SQL errors
  • Fixed: Empty time series and value fields in created charts
  • Fixed: Charts displaying no data despite successful creation

Tool Discovery Issues ​

  • Fixed: External app tools not being loaded through hooks system
  • Fixed: Inconsistent tool availability across different Frappe installations

🛠️ Technical Improvements ​

Enhanced Validation Framework ​

  • Smart Field Detection: Context-aware field auto-detection based on DocType metadata
  • Comprehensive Error Handling: Specific error types with targeted recovery suggestions
  • Pre-Creation Validation: Prevent runtime failures through upfront validation
  • DocType-Specific Logic: Tailored handling for different document types

Improved Architecture ​

  • Robust Filter Handling: Proper format conversion between user input and Frappe internals
  • Thread-Safe Operations: Enhanced plugin management with proper concurrency handling
  • Better Abstraction: Clean separation between user-friendly API and complex Frappe requirements

Code Quality ​

  • Comprehensive Testing: Added validation testing for all major functionality
  • Better Documentation: Enhanced inline documentation and examples
  • Error Recovery: Intelligent fallback mechanisms for various failure scenarios

📈 Performance Impact ​

Metric Before 2.0.1 After 2.0.1 Improvement
Document Creation Success Rate ~60% ~95% +58%
Dashboard Chart Runtime Success ~40% ~98% +145%
Tool Discovery Reliability ~80% ~99% +24%
Error Resolution Time Manual fixing required Self-guided recovery -90%

🔄 Migration Guide ​

Automatic Updates ​

Most improvements are automatically applied and require no user action.

For Dashboard Charts ​

Existing broken charts can be easily fixed:

  1. Open the chart in Dashboard Chart list
  2. Ensure "Time Series Based On" field is populated for line charts
  3. Ensure "Value Based On" field is populated for Sum/Average aggregations
  4. Charts created with v2.0.1 will work immediately

For Custom Tools ​

No changes required - custom tools will be automatically discovered on server restart.

🚨 Breaking Changes ​

None - This release is fully backward compatible.

🔍 What's Next ​

Upcoming in v2.1.0 ​

  • Enhanced visualization options with more chart types
  • Advanced dashboard templating system
  • Real-time data streaming for charts
  • Improved LLM tool descriptions with interactive examples

📋 Full Changelog ​

Added ​

  • Validate-only mode for document creation testing
  • Comprehensive field validation for dashboard charts
  • Smart field auto-detection for different DocTypes
  • Enhanced error messages with recovery guidance
  • DocType-specific chart field validation
  • Runtime chart functionality testing

Fixed ​

  • Child table handling in document creation (doc.append() vs setattr())
  • Dashboard chart field mapping (based_on, timeseries, group_by_based_on)
  • Filter format conversion (dict to list format)
  • Custom tool discovery through hooks system
  • SQL errors from non-existent field references
  • Empty chart fields causing blank dashboard displays

Improved ​

  • Document creation success rate (60% → 95%)
  • Dashboard chart reliability (40% → 98%)
  • Error message clarity and actionability
  • Tool discovery consistency across installations
  • Validation framework comprehensiveness

Technical ​

  • Enhanced plugin management with thread safety
  • Improved tool registry architecture
  • Better separation of concerns in chart creation
  • Robust error handling and recovery mechanisms
  • Comprehensive testing framework integration

🙏 Acknowledgments ​

Special thanks to the community for reporting issues and providing detailed feedback that made this comprehensive improvement possible.

📞 Support ​

Download: Release v2.0.1
License: AGPL-3.0 License
Compatibility: Frappe Framework v15+ & ERPNext v15+

v2.0.0

2025-07-22

Release Date: July 22, 2025
License: AGPL-3.0 (changed from MIT)
Breaking Changes: Yes

🌟 Release Highlights ​

This major release transforms Frappe Assistant Core into a fully extensible, plugin-based platform with enhanced visualization capabilities and stronger open source protection through AGPL-3.0 licensing.

🚀 New Features ​

🏗️ Plugin-Based Architecture ​

  • Custom Tool Development: Create your own tools using the new plugin system
  • Auto-Discovery: Zero-configuration plugin loading and registration
  • Runtime Management: Enable/disable plugins through web interface
  • Extensible Framework: Clean APIs for third-party developers
python
# Example: Creating a custom plugin
class MyBusinessPlugin(BasePlugin):
    def get_info(self):
        return {
            'name': 'my_business_plugin',
            'display_name': 'My Business Tools',
            'description': 'Custom business logic tools',
            'version': '1.0.0'
        }
    
    def get_tools(self):
        return ['sales_analyzer', 'inventory_optimizer']

📊 Enhanced Visualization System ​

  • Rebuilt Chart Engine: Complete overhaul of chart creation system
  • Advanced Dashboard Support: Improved dashboard creation and management
  • Multiple Chart Types: Bar, Line, Pie, Scatter, Heatmap, Gauge, and more
  • Better Data Handling: Improved data processing and validation
  • KPI Cards: Professional metric tracking with trend indicators

🔒 Stronger Open Source Protection ​

  • AGPL-3.0 License: Ensures modifications remain open source
  • Complete Compliance: All 125+ files properly licensed with headers
  • Network Service Requirements: Source disclosure for SaaS usage
  • Community Growth: Prevents proprietary forks while encouraging contributions

🐛 Major Bug Fixes ​

Tool Reliability Improvements ​

  • 🔧 Fixed hardcoding issues causing tool failures across multiple modules
  • 🔧 Resolved visualization tool crashes and improved error handling
  • 🔧 Fixed array dictionary handling in data processing pipelines
  • 🔧 Corrected chart field mapping - resolved x-field and y-field issues
  • 🔧 Improved dashboard creation reliability with better validation

Data Processing Enhancements ​

  • 🔧 Enhanced error handling across all 35+ tools
  • 🔧 Better data validation and sanitization procedures
  • 🔧 Improved performance in data-heavy operations
  • 🔧 Fixed edge cases in report generation and execution

⚡ Performance Improvements ​

System Optimization ​

  • 30% faster tool execution through optimized plugin loading
  • Reduced memory footprint by 25% with better resource management
  • Enhanced error recovery with graceful failure handling
  • Improved caching system for 50% faster repeated operations

Scalability Enhancements ​

  • Plugin lazy loading reduces startup time
  • Concurrent tool execution support
  • Better database query optimization
  • Enhanced connection pooling

⚖️ License Change: MIT → AGPL-3.0 ​

Strategic Decision Rationale ​

Aspect MIT (Previous) AGPL-3.0 (Current)
Freedom to Use ✅ Unlimited ✅ Unlimited
Modification Rights ✅ Unlimited ✅ Must share changes
Commercial Use ✅ Unlimited ✅ With compliance
Network Services ❌ No requirements ✅ Must provide source
Proprietary Forks ❌ Allowed ✅ Prevented

Benefits of AGPL-3.0 ​

  • 🛡️ Open Source Protection: Ensures the ecosystem remains open
  • 🌱 Community Growth: Encourages contributions over proprietary forks
  • 📡 Network Service Coverage: SaaS providers must offer source code
  • ♻️ Sustainable Development: Supports long-term community-driven development

Compliance Requirements ​

  • Source Code Availability: Must provide source for network services
  • License Propagation: Derivative works must be AGPL-3.0
  • Copyright Notices: Maintain all license headers and notices
  • User Rights: Inform users of their rights to source code

🛠️ Technical Architecture Changes ​

Before vs. After ​

Previous Architecture (v1.x) ​

Monolithic System
├── Single tool registry
├── Hardcoded tool definitions  
├── Limited extensibility
└── MIT License

New Architecture (v2.0.0) ​

Plugin-Based System
├── Dynamic plugin discovery
├── Modular tool development
├── Runtime plugin management
├── External app integration
└── AGPL-3.0 License

Plugin System Components ​

  • Base Plugin Interface: Standardized plugin development
  • Tool Registry: Automatic plugin and tool discovery
  • Plugin Manager: Lifecycle management and validation
  • Configuration System: Hierarchical plugin configuration

📋 Breaking Changes & Migration ​

License Impact ​

⚠️ Critical: Review AGPL-3.0 compliance requirements

  • All derivative works must be AGPL-3.0 licensed
  • SaaS deployments must provide source code access to users
  • Commercial use requires AGPL compliance or dual licensing

API Changes ​

⚠️ Development Impact: Some APIs have been refactored

  • Plugin Registration: New plugin-based system
  • Tool Configuration: Updated configuration format
  • Hook System: Enhanced with external app support

Migration Steps ​

For End Users ​

  1. License Review: Understand AGPL-3.0 implications
  2. Update Deployment: Test in staging environment first
  3. Verify Functionality: Ensure all tools work as expected

For Developers ​

  1. License Headers: Add AGPL-3.0 headers to custom code
  2. Plugin Migration: Convert custom tools to plugin architecture
  3. API Updates: Update to new plugin registration system

For SaaS Providers ​

  1. Compliance Review: Ensure AGPL-3.0 compliance
  2. Source Availability: Implement source code provision mechanism
  3. User Notification: Inform users of their source code rights

📊 Release Statistics ​

Codebase Metrics ​

  • 125+ Python Files: All properly licensed with AGPL-3.0 headers
  • 6 Core Plugins: Comprehensive tool coverage
  • 35+ Tools: Complete ERP integration toolkit
  • 20+ Utility Modules: Supporting infrastructure

Testing Coverage ​

  • 100% License Compliance: All files properly licensed
  • Plugin System Testing: Comprehensive plugin lifecycle tests
  • Tool Functionality: All 35+ tools verified
  • Performance Benchmarks: Confirmed improvements

Documentation Updates ​

  • Architecture Documentation: Complete plugin system guide
  • Plugin Development Guide: Step-by-step tutorial
  • License Compliance Guide: AGPL-3.0 requirements
  • Migration Documentation: Upgrade procedures

🔗 Important Resources ​

Documentation ​

Example Implementations ​

Community Support ​

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Community questions and help
  • Documentation Wiki: Comprehensive guides and examples

🔮 Future Roadmap ​

Planned Features (v2.1.0) ​

  • Plugin Marketplace: Community plugin repository
  • Advanced Analytics: Machine learning integrations
  • Real-time Collaboration: WebSocket-based features
  • Mobile Optimization: Enhanced mobile experience

Long-term Vision (v3.0.0) ​

  • Multi-tenant Architecture: Enhanced scalability
  • Advanced Security: Enhanced authentication options
  • International Support: Multi-language capabilities
  • Cloud Integration: Native cloud service integration

🙏 Acknowledgements ​

Core Contributors ​

  • Paul Clinton - Lead Developer & Architecture
  • Community Contributors - Feedback, and suggestions

📞 Support & Contact ​

Community Support ​

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and community help
  • Documentation: Comprehensive guides and examples

Professional Services ​

  • Custom Development: Tailored solutions and integrations
  • Implementation Support: Expert setup and configuration
  • Training & Consulting: Team training and best practices
  • Contact: [email protected]

⚠️ Important Notes ​

Pre-Upgrade Checklist ​

  • [ ] Review AGPL-3.0 license requirements
  • [ ] Test upgrade in staging environment
  • [ ] Backup current installation
  • [ ] Update any custom integrations
  • [ ] Verify plugin configurations

Post-Upgrade Verification ​

  • [ ] All tools execute successfully
  • [ ] Plugins load correctly
  • [ ] Visualizations render properly
  • [ ] Performance meets expectations
  • [ ] License compliance confirmed

🎉 Ready to explore v2.0.0? Start with our Quick Start Guide and Plugin Development Tutorial!

v1.3.0

2025-07-14

Release Notes - Frappe Assistant Core v1.3.0 ​

🔒 Security & Reliability Release ​

This release focuses on comprehensive security enhancements and code refactoring to ensure robust, secure AI assistant operations within Frappe Framework environments.

🔐 Security Enhancements ​

Multi-Layer Security Framework ​

  • Role-Based Access Control: Implemented comprehensive role-based tool access with System Manager, Assistant Admin, Assistant User, and Default user categories
  • Document-Level Permissions: Deep integration with Frappe's permission system using frappe.has_permission() for both DocType and document-specific access control
  • Row-Level Security: Automatic enforcement of company-based filtering and user-specific data access through Frappe's built-in permission engine
  • Field-Level Security: Sensitive field filtering and data masking based on user roles

Enhanced Permission Validation ​

  • Multi-layer validation: Role → DocType → Document → Field level security checks
  • Submitted document protection: Prevents modification/deletion of submitted documents without proper permissions
  • Administrator account protection: Special hardcoded protection for Administrator access
  • Dynamic permission queries: Custom permission query conditions for audit logs and connection logs

Sensitive Data Protection ​

  • Comprehensive field masking: Automatic filtering of passwords, API keys, tokens, and other sensitive data
  • Admin-only fields: Restricted access to system metadata and administrative fields for non-admin users
  • DocType restrictions: Complete access restriction to system administration DocTypes for Assistant Users

🔍 Audit & Monitoring ​

Comprehensive Audit Trail ​

  • Tool execution logging: Complete audit trail of all assistant tool usage with user, arguments, and results
  • Document change tracking: Automatic logging of document updates, submissions, and cancellations
  • Access attempt logging: Recording of both successful and failed access attempts
  • User-scoped audit access: Users can only view their own audit logs (except administrators)

Security Monitoring ​

  • Permission validation logging: Detailed logging of permission checks and failures
  • IP address tracking: Connection and access monitoring with IP-based audit trails
  • Cache invalidation: Automatic cache refresh for security-critical settings changes

🏗️ Code Refactoring & Architecture ​

Security Configuration Centralization ​

  • Unified security config: Centralized security policies in security_config.py
  • Role-based tool matrix: Clear definition of tool access permissions per role
  • Sensitive field registry: Comprehensive mapping of sensitive fields across all DocTypes
  • Restricted DocType definitions: Explicit listing of DocTypes restricted by user role

Enhanced Tool Security ​

  • Base tool security framework: Consistent security validation across all assistant tools
  • Permission checking standardization: Unified validate_document_access() function used across all document operations
  • User context preservation: Proper user context flow throughout the assistant system
  • No permission bypass: Explicit ignore_permissions=False enforcement in data queries

Performance & Reliability ​

  • Permission caching considerations: Framework ready for permission result caching
  • Error handling improvements: Better error messages and graceful failure handling
  • Security-first design: All new features implement security checks by default

🛠️ Technical Improvements ​

Framework Integration ​

  • Deep Frappe integration: Leverages Frappe Framework's built-in security mechanisms
  • Standard compliance: Follows Frappe security best practices and conventions
  • Permission query hooks: Proper implementation of permission query conditions
  • Role-based filtering: Automatic application of role-based data visibility rules

Code Quality ​

  • Security-by-design: All tools implement comprehensive permission checking
  • Consistent error handling: Standardized security error responses across tools
  • Documentation improvements: Enhanced inline documentation for security functions
  • Type safety: Improved type annotations for security-critical functions

📋 Migration Notes ​

For Administrators ​

  • New roles available: Assistant Admin and Assistant User roles with specific permission sets
  • Audit log access: New audit logging system for monitoring assistant usage
  • Security settings: Review and configure tool access permissions as needed

For Developers ​

  • Security validation required: All new tools must implement validate_document_access()
  • Role-based development: Consider user roles when developing new assistant features
  • Permission checking: Use centralized security functions for consistent behavior

🔧 System Requirements ​

  • Frappe Framework: Compatible with standard Frappe permission system
  • Database: No schema changes required - uses existing permission tables
  • Caching: Optional Redis caching for improved permission check performance

📊 Security Statistics ​

  • Tool access control: 4 distinct user role categories with specific permission sets
  • Sensitive field protection: 50+ sensitive fields automatically filtered
  • DocType restrictions: 30+ administrative DocTypes restricted for Assistant Users
  • Audit coverage: 100% tool execution logging with comprehensive audit trail

🚀 Upgrade Instructions ​

  1. Backup your site: Always backup before upgrading
  2. Pull latest changes: git pull origin main
  3. Run migrations: bench migrate
  4. Clear cache: bench clear-cache
  5. Restart services: bench restart

🤝 Contributors ​

This release includes security enhancements and code refactoring to ensure robust AI assistant operations.

Full Changelog: View on GitHub

Download: Source Code (zip) | Source Code (tar.gz)

v1.2.0

2025-07-04

Release Date: July 4, 2025
Type: Major Feature Release
Compatibility: ✅ Full backward compatibility

🎉 What's New in v1.2.0 ​

This release transforms Claude for Frappe ERP from a functional extension into a production-ready, professionally documented, and developer-friendly platform. We've completely redesigned the architecture with a plugin-based system, added comprehensive build tools, fixed critical data handling issues, and created extensive documentation following official Anthropic standards.

🚀 Major Features ​

🏗️ Plugin-Based Architecture ⭐ NEW ​

  • Modular Design - Complete conversion from monolithic to plugin-based architecture
  • Plugin Auto-Discovery - Automatic detection and loading of plugins from frappe_assistant_core/plugins/
  • Plugin Manager - Centralized plugin management with validation and lifecycle control
  • Tool Registry - Dynamic tool registration and management across plugin categories
  • Plugin Categories - Organized into core, data_science, websocket, and batch_processing plugins
  • BaseTool Inheritance - Standardized tool development with consistent interfaces
  • Hot Reloading - Plugin refresh functionality for development workflow
  • Enhanced Extensibility - Easy addition of new tools and plugins without core modifications
python
# Plugin structure example
frappe_assistant_core/
├── plugins/
│   ├── core/               # Essential ERP operations
│   ├── data_science/       # Analytics and visualization
│   ├── websocket/          # Real-time communication
│   └── batch_processing/   # Background operations

📦 Professional Build System ​

  • build.py - One-command DXT package creation
  • validate_manifest.py - 25+ validation rules
  • Automated Testing - Syntax checking and integration validation
  • Cross-Platform Support - Windows, macOS, and Linux
bash
# Simple build process
python validate_manifest.py  # Comprehensive validation
python build.py             # Creates claude-for-frappe-v1.2.0.dxt

📚 Comprehensive Documentation ​

🏗️ Client Packages Architecture ​

  • Future-Ready Structure - Prepared for ChatGPT, Copilot, and other AI platforms
  • Scalable Organization - client_packages/claude-desktop/
  • Cross-Platform Roadmap - Ready for multi-AI ecosystem

🔧 Critical Bug Fixes ​

Data Analysis Tools Fixed ​

  • ✅ Resolved invalid __array_struct__ errors with Frappe data
  • ✅ Enhanced pandas DataFrame compatibility
  • ✅ SQL-based data fetching bypasses problematic frappe._dict objects
  • ✅ Robust data conversion handles complex Frappe data types

Visualization Tool Improvements ​

  • ✅ Fixed matplotlib import scope issues
  • ✅ Proper parameter passing in chart creation methods
  • ✅ Enhanced error handling with meaningful messages

Python Execution Enhancements ​

  • ✅ Clean data serialization for pandas compatibility
  • ✅ Improved error reporting for debugging
  • ✅ Better type handling across all data science tools

📊 Impact & Benefits ​

Feature Before v1.2.0 After v1.2.0
Build Process Manual ZIP creation Automated python build.py
Validation Manual checking 25+ automated validation rules
Documentation Basic README Comprehensive BUILD.md + official links
Data Compatibility Frequent __array_struct__ errors ✅ Seamless pandas integration
Visualization plt not defined errors ✅ All chart types working
Developer Experience Complex setup Professional toolchain
Architecture Monolithic single file ✅ Plugin-based modular system

🛠️ Technical Improvements ​

Plugin Architecture Redesign ​

  • Modular Tool Organization - 21 tools now organized across 4 plugin categories
  • Plugin Manager System - Centralized plugin lifecycle management and validation
  • Tool Registry - Dynamic tool discovery and registration system
  • BaseTool Framework - Standardized inheritance pattern for all tools
  • Plugin Auto-Discovery - Automatic scanning and loading of plugins
  • Enhanced Extensibility - Easy addition of new tools without core modifications
  • Development Workflow - Plugin refresh and hot-reloading capabilities

Data Processing Engine ​

  • SQL-Based Queries - Direct database access bypassing object conversion issues
  • Smart Type Conversion - Handles datetime, decimal, and complex Frappe types
  • Enhanced Serialization - JSON-compatible data throughout the pipeline

Build & Validation System ​

  • Comprehensive Manifest Validation - Follows Anthropic's official specification
  • Automated Testing - Python syntax, file existence, URL validation
  • Cross-Platform Compatibility - Works on all major operating systems
  • Professional Error Reporting - Clear, actionable error messages

Extension Architecture ​

  • Client Packages Structure - client_packages/claude-desktop/
  • Future AI Platform Support - Ready for ChatGPT, Copilot, and others
  • Modular Design - Independent versioning and documentation per platform

🔄 Migration Guide ​

For End Users ​

  • ✅ No changes required - Full backward compatibility
  • ✅ Same installation process - Double-click DXT file
  • ✅ Same configuration - No settings changes needed
  • ✅ Better reliability - Fewer errors, more stable operation

For Developers ​

  • 📦 New build tools available - Use python build.py for packaging
  • 📚 Enhanced documentation - See BUILD.md for complete guides
  • 🔧 Better testing - Use python validate_manifest.py before releases
  • 🏗️ New project structure - Extension moved to client_packages/claude-desktop/

📥 Installation ​

Build from Source ​

bash
git clone https://github.com/clinu/Frappe_Assistant_Core.git
cd Frappe_Assistant_Core/client_packages/claude-desktop
python validate_manifest.py  # Validate first
python build.py             # Build DXT package

🧪 Testing ​

This release has been extensively tested:

  • ✅ All 21 tools functional and tested
  • ✅ Data analysis workflows working without errors
  • ✅ Visualization creation successful across all chart types
  • ✅ Cross-platform compatibility verified on Windows, macOS, Linux
  • ✅ Build system tested with multiple configurations
  • ✅ Manifest validation covers all edge cases

📋 What's Fixed ​

Critical Issues Resolved ​

  • 🐛 invalid __array_struct__ errors when creating pandas DataFrames from Frappe data
  • 🐛 name 'plt' is not defined errors in visualization tool
  • 🐛 Matplotlib import scope issues affecting chart creation
  • 🐛 Data serialization problems with complex Frappe objects
  • 🐛 Python execution environment inconsistencies

Improvements Made ​

  • 🔧 Enhanced error messages with actionable guidance
  • 🔧 Better debugging capabilities for development
  • 🔧 Improved performance in data processing tools
  • 🔧 More robust error handling across all tools
  • 🔧 Professional development workflow established

🌟 New Capabilities ​

For Business Users ​

  • More Reliable Data Analysis - No more mysterious errors when analyzing business data
  • Better Visualizations - All chart types now work correctly
  • Faster Performance - Optimized data processing for large datasets
  • Enhanced Error Messages - Clear explanations when something goes wrong

For Developers ​

  • Professional Build Tools - Industry-standard development workflow
  • Comprehensive Documentation - Everything needed to contribute or extend
  • Automated Validation - Catch issues before they reach production
  • Future-Ready Architecture - Easy to add support for new AI platforms

🔗 Resources ​

New Documentation ​

Official References ​

Community ​

🚧 Known Issues ​

  • Icon Size Warning - The current icon (1.7MB) could be optimized for faster loading
  • Development Logs - Some verbose logging in development mode (can be disabled)

🔮 What's Next ​

Upcoming in v1.3.0 ​

  • 🔄 Real-time Data Streaming - Live updates from Frappe server
  • 📊 Advanced Analytics - Machine learning insights and predictions
  • 🎨 Enhanced Visualizations - Interactive charts and dashboards
  • 🔧 Performance Optimizations - Even faster data processing

Future Roadmap ​

  • 🤖 ChatGPT Plugin - client_packages/chatgpt-plugin/
  • 👨‍💻 GitHub Copilot Extension - client_packages/copilot-extension/
  • 📚 Direct API SDK - client_packages/api-sdk/
  • 🌐 Web-based Interface - Browser extension for Frappe

🙏 Acknowledgments ​

  • Anthropic for Claude Desktop and MCP protocol
  • Frappe Framework for the amazing ERP platform
  • Community Contributors for feedback and testing
  • Early Adopters who reported issues and helped improve the extension

Download Claude for Frappe ERP v1.2.0 today and experience the most reliable, feature-complete AI-powered ERP integration available! 🚀

Download DXT Documentation Official Docs

v1.1.1

2025-07-03

🐛 Bug Fixes ​

Fixed Critical Installation Issue with bench get-app ​

  • Issue: Users were unable to auto-install the app using the bench get-app command
  • Root Cause: App name contained hyphens (-) which caused compatibility issues with Frappe's installation process
  • Solution:
    • Renamed app to use underscores (_) instead of hyphens
    • Removed unnecessary setup.py file that was causing conflicts

💥 Breaking Changes ​

⚠️ App Name Change: If you have an existing installation, you may need to update your references from the old hyphenated name to the new underscored name.

📋 Migration Guide ​

For existing installations:

bash
# Remove old app (if installed)
bench remove-app [old-app-name-with-hyphens]

# Install the updated version
bench get-app [new-app-name-with-underscores]

v1.1.0

2025-06-30

🚀 Release v1.1.0 - Major Architecture Enhancement ​

We're excited to announce the release of v1.1.0, featuring significant architectural improvements, WebSocket support, advanced caching, and comprehensive testing infrastructure. This release transforms the MCP Frappe integration into a production-ready solution with enterprise-grade features.

✨ Major Features ​

🌐 WebSocket MCP Server Integration ​

  • Real-time Communication: WebSocket-based MCP server with persistent connections
  • Session Authentication: Frappe session-based authentication for WebSocket connections
  • Batch Processing: Parallel execution capabilities for multiple operations
  • Progress Streaming: Real-time progress updates with cancellation support for long-running operations

⚡ Advanced Caching System ​

  • Intelligent Caching: Multi-layer caching with TTL policies and selective invalidation
  • Cache Warming: Proactive cache population strategies with performance monitoring
  • Frappe Integration: Seamless integration with Frappe's built-in caching mechanisms
  • High Availability: Support for both in-memory and Redis-based caching with automatic failover

🛠️ Enhanced Tool Execution Framework ​

  • Robust Error Handling: Comprehensive error management with detailed logging and user-friendly messages
  • Resource Monitoring: Resource limits and monitoring for intensive operations
  • Operation Control: Cancellation support and progress tracking for batch processes
  • Advanced Analysis: Python code execution capabilities with integrated data visualization tools

🧪 Comprehensive Testing Infrastructure ​

  • 100% Test Success: Achieved complete test suite success (resolved all 57 initial failures)
  • Fixed Critical Issues: Resolved MagicMock pickling issues in Redis cache integration
  • Improved Reliability: Corrected method naming and response structure patterns
  • Enhanced Mocking: Updated mock patterns to match Frappe's actual object access behaviors

🔧 Core Infrastructure Improvements ​

🔐 API & Authentication Enhancements ​

  • Token Authentication: Added robust token-based authentication support
  • Session Integration: Seamless integration with Frappe session management
  • WebSocket APIs: New real-time communication endpoints
  • Error Handling: Improved error propagation and response formatting

📦 Tool Registry & Management ​

  • Dynamic Loading: Enhanced tool registration with dynamic loading capabilities
  • Better Discovery: Improved tool discovery and metadata management
  • Validation: Comprehensive tool validation and error handling

📚 Documentation & Development Experience ​

  • Comprehensive Guides: Complete development guides and implementation templates
  • Best Practices: Tool development templates with verified patterns
  • Feature Documentation: Enhanced documentation with practical examples

🐛 Bug Fixes ​

  • Authentication Flow: Fixed API authentication issues preventing MCP protocol requests
  • Startup Process: Resolved startup.py execution on bench restart
  • Code Cleanup: Removed redundant and unused components
  • Session Handling: Improved user context setting for authenticated requests

🚀 Performance Improvements ​

  • 80% Faster Responses: Intelligent caching reduces API response times significantly
  • Parallel Processing: Batch operations enable concurrent execution
  • Reduced Overhead: WebSocket connections eliminate HTTP overhead for real-time operations
  • Resource Optimization: Smart resource monitoring prevents system overload

🔄 Breaking Changes ​

None - All changes are backward compatible with existing implementations.

📦 Installation & Upgrade ​

New Installation ​

bash
bench get-app https://github.com/clinu/Frappe-Assistant-Core.git
bench install-app frappe_assistant_core

Upgrade from Previous Version ​

bash
bench update
bench migrate

The application will automatically start the MCP server and register all tools upon installation or restart.

🔍 What's Changed ​

New Components ​

  • WebSocket MCP server implementation
  • Advanced caching system with Redis support
  • Batch request processing capabilities
  • Real-time progress streaming
  • Comprehensive error management framework

Enhanced Components ​

  • MCP server core with WebSocket support
  • API endpoints with improved authentication
  • Tool management and registration system
  • Application hooks and startup processes
  • Dashboard functionality and user interface

Developer Experience ​

  • Complete testing infrastructure overhaul
  • Development templates and best practices guide
  • Enhanced debugging and logging capabilities
  • Comprehensive feature documentation

📋 Full Changelog ​

[v1.0.0...v1.1.0](https://github.com/your-repo/mcp-frappe/compare/v1.0.0...v1.1.0)

For detailed implementation guides and API documentation, visit our documentation.

Report issues or request features on our [GitHub Issues](https://github.com/your-repo/mcp-frappe/issues) page.

v1.0.1

2025-06-28

🚀 Features ​

Automatic Artifact Streaming System ​

Implement comprehensive artifact streaming for all tools

We've introduced an intelligent artifact streaming system that significantly improves handling of large tool results and enhances user experience:

Key Improvements:

  • Smart Detection: Automatically detects large results (>5 lines or >1000 characters) and streams them appropriately
  • Tool Categorization: Intelligent categorization system for different tool types with specific handling logic
  • Flexible Display Modes:
    • Preview mode for results under 10k characters
    • Truncated mode for results over 10k characters
  • Enhanced Workflow: Mandatory streaming instructions prevent conversation length limits
  • Professional Deliverables: Tool-specific artifact type suggestions and section templates

Technical Enhancements:

  • Resolved timestamp serialization errors in analyze_frappe_data tool
  • Added automatic import statement removal in execute_python_code tool
  • Fixed NoneType startswith errors in report execution
  • Comprehensive streaming guidance and formatting improvements

🐛 Bug Fixes ​

Admin Panel API and Statistics Resolution ​

Resolve critical admin panel functionality and usage statistics display

Fixed multiple API-related issues that were preventing proper admin panel operation and statistics display:

API Endpoints:

  • Added missing API endpoints: get_usage_statistics, ping, force_test_logging
  • Fixed server control methods by adding required @frappe.whitelist decorators
  • Ensured proper response format matching frontend expectations (success/error structure)

Database and Query Fixes:

  • Corrected database column references (date → creation) in statistics queries
  • Removed unsupported ignore_permissions parameter from db.count() calls
  • Resolved table existence check issues in tool registry queries
  • Enhanced error handling with graceful fallbacks for missing data

Impact:

  • Admin panel now fully functional with all control methods working
  • Usage statistics display correctly with proper data formatting
  • Improved system reliability with better error handling

📋 Summary ​

This release focuses on improving system reliability and user experience through enhanced artifact streaming capabilities and critical admin panel fixes. The automatic streaming system ensures better handling of large datasets while the API fixes restore full admin functionality.

Total Changes:

  • 1 major feature enhancement
  • 7+ critical bug fixes
  • Improved error handling and system stability

🔄 Migration Notes ​

No breaking changes in this release. All improvements are backward compatible.

Older versions: all releases on GitHub →