Frappe Assistant Core
README.md
# Frappe Assistant Core
> Talk to your ERPNext site. FAC lets Claude, ChatGPT, and other
> MCP-ready LLMs work directly with your invoices, customers, stock,
> workflows, and custom apps — inside your ERPNext permissions, with
> every call logged.
[](https://github.com/buildswithpaul/Frappe_Assistant_Core/releases)
[](https://pypi.org/project/frappe-assistant-core)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://docs.assistantcore.cloud/api/tool-reference)
[](https://docs.assistantcore.cloud)
[](https://github.com/buildswithpaul/Frappe_Assistant_Core/actions/workflows/ci.yml)
[](https://cloud.frappe.io/marketplace/apps/frappe_assistant_core)
[](https://github.com/buildswithpaul/Frappe_Assistant_Core/stargazers)
[](https://github.com/buildswithpaul/Frappe_Assistant_Core/network/members)
[](https://github.com/sponsors/buildswithpaul)
---
## New in FAC 3.0: FAC Chat
FAC 3.0 introduces **FAC Chat** — an opt-in, in-Frappe AI chat assistant
powered by **FAC Cloud**, our managed service. What it does, what it
costs and how to sign up: **<https://fac-suite.com>**.
FAC now offers two ways to use it:
- **BYO-LLM (MCP server, free)** — the original FAC. Connect any
MCP-ready LLM client (Claude Desktop, Cursor, ChatGPT desktop, etc.)
to your Frappe data over MCP. You bring the LLM, you pay your own
LLM bill, nothing leaves your stack. Ships enabled by default.
- **FAC Chat (in-Frappe chat UI, SaaS)** — opt-in. A native chat
widget on every Desk page plus a full-screen SPA at `/copilot`,
powered exclusively by **FAC Cloud**. One subscription covers LLM
access across providers, conversation memory, RAG, and workflow
automation. Ships **disabled by default**. See
<https://fac-suite.com>.
The split is intentional: BYO-LLM keeps the existing free MCP path
untouched; FAC Chat is the managed experience for teams that want the
chat inside Frappe without wiring up their own LLM keys. See
[FAC Chat](#fac-chat) below for full details.
---
## What you get
Once FAC is installed, your team can ask an LLM for things they'd
normally do by hand:
> *"Show me overdue invoices from our top five customers."*
>
> *"Update this lead's status to Qualified and set next action date to
> Monday."*
>
> *"Run the monthly revenue report and summarise the top movers."*
>
> *"How much stock of SKU-1234 do we have across all warehouses?"*
Behind that simple interaction, FAC exposes **24 built-in tools** for
the things your team does every day — document CRUD, search, reports,
workflows, analytics, file extraction, and dashboards. Admins can
publish **Skills** (reusable instructions that teach the LLM how to
handle a specific job) and **Prompt Templates** (saved starting points
users can pick from the admin UI) so answers stay consistent and use
the right reports. The LLM authenticates over **OAuth 2.0** as a real
ERPNext user, so it only sees data that user can already see in the
desk. Every call is recorded in the **Assistant Audit Log**.
It's a Frappe app, so developers can extend the toolset from their own
Frappe apps through a hook — your data model, your business logic,
scoped per your app.
Your data stays in your site. You control which LLM connects.
---
## Quick start
Two install paths depending on how you run Frappe.
### On Frappe Cloud (recommended)
1. Go to your site's **Apps** tab in the Frappe Cloud dashboard.
2. Find **Frappe Assistant Core** in the marketplace and click **Install**.
3. Frappe Cloud installs and migrates the app for you.
Marketplace: <https://cloud.frappe.io/marketplace/apps/frappe_assistant_core>
### On self-hosted bench
```bash
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site <your-site> install-app frappe_assistant_core
```
**Node 22+ is needed 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.
Requires Frappe v15 or v16 and Python 3.10+.
### Connect your LLM
Once installed, the same four steps work for any MCP-compatible client.
Example shown for Claude Desktop:
1. Go to **Desk → FAC Admin** and copy the **MCP Endpoint URL**.
2. In **Claude Desktop → Settings → Connectors → Add Custom Connector**,
paste the URL and click **Add**.
3. Click **Connect**, log in with your ERPNext account, and authorize.
4. Ask Claude something — for example, *"List all customers created this
month."*
For ChatGPT, Claude Web, and MCP Inspector walkthroughs, see the
[Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) on the docs site.
---
## FAC Chat
**FAC Chat is an opt-in, SaaS-powered chat experience that ships inside
FAC.** Where the MCP server lets external LLM clients (Claude Desktop,
Cursor, ChatGPT desktop) talk to your Frappe data with your own LLM
keys, FAC Chat brings the conversation inside Frappe itself — a widget
on every Desk page and a full-screen SPA at `/copilot` — powered by a
**FAC Cloud** subscription.
Plans, pricing and sign-up live at **<https://fac-suite.com>**; this
section covers only what the app itself does.
### Two ways to use FAC
| Option | What it is | LLM | Cost | Where the chat lives |
|---|---|---|---|---|
| **BYO-LLM (MCP server)** | The original FAC. Exposes Frappe data over MCP to any MCP-ready client. | You bring your own (Anthropic, OpenAI, Gemini, Bedrock, etc.) | Free. You pay your own LLM bill. | In your external MCP client (Claude Desktop, Cursor, etc.). No chat UI inside Frappe. |
| **FAC Chat (SaaS)** | In-Frappe chat widget + `/copilot` SPA. Streaming, tool use, attachments, history, memory, RAG, workflows. | Managed by FAC Cloud. One subscription, multiple providers. | Subscription required. Sign up flow runs inside the chat UI. | Inside Frappe Desk. |
These are **mutually exclusive at the chat layer**: the in-Frappe chat
UI is only available through FAC Cloud. There is no BYO-LLM
path for FAC Chat — if you want to bring your own LLM, use the MCP
server.
Both options share the same plugin registry, the same
`Assistant Audit Log`, and the same OAuth-based authentication.
Enabling FAC Chat does NOT change anything for your MCP clients — both
can run side by side.
### Enabling FAC Chat
1. Open **FAC** from the Frappe apps screen.
2. Enable chat.
That is the whole thing — **no `bench restart`**. The chat hooks are
registered unconditionally and every consumer checks the toggle at
request time, so other workers pick up the new state on their next
request.
A discovery banner on the Desk landing page will also walk admins
through enabling chat — it appears once per admin and can be dismissed.
After enabling:
- The chat widget appears in the corner of Frappe Desk pages.
- The full-screen SPA is reachable at `/copilot`.
- The first time a user opens chat, they walk through a one-time
onboarding that registers the tenant with FAC Cloud and links it to
a subscription.
### What FAC Chat is NOT
- It is **not required** for MCP server users. Skip it entirely if
Claude Desktop or another MCP client is your only access pattern —
the free MCP path keeps working exactly as before.
- It is **not a BYO-LLM frontend**. The in-Frappe chat UI talks only
to FAC Cloud. If you want to bring your own LLM keys, the MCP server
is the path for that.
- It does **not change** FAC's tool catalog. The same 24 built-in
tools are available to MCP clients and to FAC Chat alike.
- It does **not store conversations off-site without consent**.
Conversation history lives in your Frappe database; only the LLM
request payload (messages + tool call results) is forwarded to
FAC Cloud to generate the next response.
---
## Skills and Prompt Templates
FAC gives you two ways to shape what the LLM does with your data.
**Skills** are reusable instructions you give the LLM — stored as
`FAC Skill` documents inside your site. Each skill has a `skill_id`,
a description, and markdown content describing how to handle a specific
task using the available tools. The LLM lists skills on connect and
pulls them on demand, so every time someone asks about, say, the
monthly sales close, the answer is consistent and uses the right
reports.
**Prompt Templates** are saved starting points for the *user's* side
of the conversation — Jinja-templated prompts with typed arguments
(dropdowns, dates, booleans). Authors publish them from the admin page;
users pick one, fill in the arguments, and the rendered prompt is sent
to the LLM. Use them for frequently-asked analyses like "Sales
Analysis", "Manufacturing Analysis", or your own industry-specific
workflows.
Both live in Frappe, so they're version-controlled with your site,
shareable across users, and can be shipped by external Frappe apps
through the `assistant_skills` hook.
---
## Tools at a glance
FAC ships 22 tools across four plugins: **Core** (Frappe operations),
**Data Science** (Python execution, analytics, file extraction),
**Visualization** (dashboards and charts), and **Custom Tools** (the
registry for tools contributed by external apps).
| Category | Tools |
|---|---|
| Documents | `get_document`, `list_documents`, `create_document`, `update_document`, `delete_document`, `document_action` |
| Search | `search_documents` (global, DocType-scoped, or Link value), plus `search` / `fetch` for ChatGPT connectors |
| Reports | `report_list`, `report_requirements`, `generate_report` |
| Approvals | `get_pending_approvals`, `run_workflow` |
| Schema | `get_doctype_info` |
| Analytics | `run_python_code`, `run_database_query` |
| Files | `extract_file_content` |
| Dashboards | `create_dashboard`, `create_dashboard_chart`, `list_user_dashboards` |
Full specification for each tool is in the
[Tool Reference](https://docs.assistantcore.cloud/api/tool-reference).
---
## Schema access is live
FAC reads your schema from Frappe's metadata API at the moment a tool is
called. It keeps no schema copy of its own — no snapshot table, no
embedded or vector index of your data model, and no sync command. There
is nothing to re-run and no staleness window to reason about.
In practice that means:
- **Custom DocTypes, Custom Fields, and Property Setters are visible on
the next tool call.** Create a field in the desk and the LLM sees it
immediately. `get_doctype_info` returns custom fields merged inline
with standard fields, along with child-table field definitions, Link
targets, and the DocType's permission rules.
- **Renames, added options, and changed labels take effect the same
way** — they come from the same live metadata read.
- **Permissions are evaluated per call against the requesting user**,
never snapshotted. FAC asks Frappe on each call, so a role change
applies as soon as Frappe applies it.
FAC does cache a few operational things — whether the server is
enabled, the MCP and OAuth endpoint URLs, and dashboard/health
statistics. None of them describe your schema or your data.
If you reach FAC through another product that embeds or orchestrates it,
that layer may maintain its own schema cache with its own refresh
behaviour. Staleness seen through a wrapper is worth tracing there
first; FAC itself has no such step.
---
## Extend with your own tools
If you have a Frappe app and want the LLM to reach into it, use the
`assistant_tools` hook in your app's `hooks.py`. This is the recommended
path — tools travel with the app, survive upgrades, and stay scoped to
your data model. The same pattern works for Skills via the
`assistant_skills` hook.
If you need to modify core FAC behaviour instead, write an internal
plugin.
See the [External App Development guide](docs/development/EXTERNAL_APP_DEVELOPMENT.md)
for the hook contract, and the
[Plugin Development guide](docs/development/PLUGIN_DEVELOPMENT.md) for
internal plugins.
---
## Authentication & security
FAC uses OAuth 2.0 with PKCE for LLM connections — the LLM never sees
the user's Frappe password. Every tool call is scoped to the calling
user's Frappe and ERPNext roles and permissions: if the user cannot
read a DocType in the desk, they cannot read it through the LLM either.
Every call is logged to `Assistant Audit Log` with caller, tool,
arguments, and result status, so admins always have a full record of
what the LLM did.
For setup and advanced configuration:
- [OAuth Setup Guide](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide)
- [Code Execution Security](https://docs.assistantcore.cloud/guides/code-execution-security)
- [MCP StreamableHTTP Guide](https://docs.assistantcore.cloud/internals/mcp-streamable-http)
---
## Documentation
**📚 Full docs are at [docs.assistantcore.cloud](https://docs.assistantcore.cloud)**
Common entry points:
- [Installation](https://docs.assistantcore.cloud/getting-started/installation) — Frappe Cloud one-click + self-hosted bench
- [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) — connect Claude Desktop in 5 minutes
- [OAuth Setup Guide](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide) — production OAuth configuration
- [Tool Reference](https://docs.assistantcore.cloud/api/tool-reference) — every built-in tool
- [fac-suite.com](https://fac-suite.com) — FAC Chat and FAC Cloud: what they do, plans, and sign-up
- [API Reference](https://docs.assistantcore.cloud/api/reference) — MCP and OAuth protocol surface
- [Architecture](https://docs.assistantcore.cloud/internals/architecture) — how FAC is put together
- [Changelog](https://docs.assistantcore.cloud/reference/changelog) — release notes
For contributors editing this repo, see [`docs/development/`](docs/development/) and [Contributing.md](Contributing.md).
---
## Sponsor and professional services
Frappe Assistant Core is built and maintained in the open. If it saves
your team time, please consider sponsoring ongoing maintenance and new
features on [GitHub Sponsors](https://github.com/sponsors/buildswithpaul)
— recurring or one-time contributions.
Professional implementation, customization, training, and enterprise
support are delivered by our official services partner
[Promantia](https://promantia.com). Reach them at
[ai-support@promantia.com](mailto:ai-support@promantia.com), or register
your project at
<https://erp.promantia.in/fac-registration/new>. Full details in
[COMMERCIAL.md](COMMERCIAL.md).
The software itself remains completely free and open source under
AGPL-3.0. Professional services are optional.
---
## License
AGPL-3.0 — see [LICENSE](LICENSE).
For dual-licensing, new partnerships, or sponsorship inquiries, contact
<jypaulclinton@gmail.com>.
## Contributing
Contributions welcome. See [Contributing.md](Contributing.md) for the
pull-request workflow and coding standards.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessResponsive