@solumflow-app/crm-mcp-server 0.12.0 → 0.14.0

package/README.md

@@ -34,6 +34,13 @@ Any other MCP client takes the same command and the same two variables:
 
 The server speaks over stdio. Errors go to stderr.
 
+The same set of tools can be put on any `McpServer` with
+`registerSolumFlowTools(server, client, { clientVersion, baseUrl, connectedAs })`
+from `@solumflow-app/crm-mcp-server/register-tools`. `connectedAs` is `'key'`
+for a server that runs on a key, as this one does, and `'app'` for one that
+runs on the token of an app connected through OAuth as a person: the app uses
+that for its online server, which then also has the knowledge base tools.
+
 ## Skills
 
 The skills that walk an agent through connecting a website (a menu with
@@ -90,10 +97,145 @@ scope the key lacks answers `forbidden` and names the scope it needs.
 | `list_api_webhooks` | `shop:manage` | The addresses told about changes, never their signing keys. |
 | `upsert_api_webhook` | `shop:manage` | Make or change one, such as the site's revalidation route; a new one answers its signing key once. |
 | `run_test_order` | `shop:manage`, `cart:write`, `orders:write`, `orders:read` | Cart, postage, order and a payment with Stripe's test card, read back until paid. Only in test mode. |
+| `list_currencies` | `catalog:read` | The currencies the shop sells in, its own first. |
+| `upsert_products` | `catalog:write` | Make or change many products in one call, each known by `source` + `externalRef`. |
+| `set_product_extras` | `catalog:write` | Set what may be taken with a product. |
+| `set_product_options` | `catalog:write` | Set the options with a surcharge on a product. |
+| `delete_product` | `catalog:write` | Delete a product for good. |
+| `delete_field` | `catalog:write` | Take a catalogue field away (to the trash). |
+| `restore_field` | `catalog:write` | Bring a catalogue field back from the trash. |
+| `get_category_by_ref` | `catalog:read` | Find a category by your own reference. |
+| `upload_catalog_file` | `catalog:write` | Upload a picture or a file from disk for a product. |
+| `get_consent_banner` | `website:manage` | Read the cookie banner. |
+| `update_consent_banner` | `website:manage` | Set the cookie banner. |
+| `list_form_definitions` | `forms:manage` | The forms to build, with their status. |
+| `get_form_definition` | `forms:manage` | One form as the builder keeps it: fields, settings, spam settings. |
+| `create_form` | `forms:manage` | Make an empty draft form. |
+| `update_form` | `forms:manage` | Change a form, or publish it. |
+| `get_hosting_order_page` | `hosting-order:manage` | Read the hosting order page. |
+| `update_hosting_order_page` | `hosting-order:manage` | Set up the hosting order page. |
+| `get_order` | `orders:read` | One order by number, id or PaymentIntent: status, lines, totals, the seller's mark and the customer account it made. Never the buyer. |
+| `list_orders` | `orders:read` | The orders, a page by id; `sellerRef` narrows them to those paid through a link with `?ref=<sellerRef>`. |
+| `list_record_lists` | `records:read` | The lists of contacts, companies and own records. |
+| `search_records` | `records:read` | Search the records of one list. |
+| `get_record` | `records:read` | One record with its fields. |
+| `create_record` | `records:write` | Make a record. |
+| `update_record` | `records:write` | Change a record. |
+| `list_tags` | `records:read` | The tags of the account. |
+| `list_notes` | `records:read` | The notes on a record. |
+| `add_note` | `records:write` | Write a note on a record. |
+| `upsert_contact` | `contacts:write` | Add a contact, or find the one already known. |
+| `list_pipelines` | `deals:read` | The pipelines and their stages. |
+| `list_deals` | `deals:read` | Deals, by pipeline, stage or contact. |
+| `get_deal` | `deals:read` | One deal. |
+| `create_deal` | `deals:write` | Make a deal. |
+| `update_deal` | `deals:write` | Change or move a deal. |
+| `list_deal_notes` | `deals:read` | The notes on a deal. |
+| `add_deal_note` | `deals:write` | Write a note on a deal. |
+| `list_tax_rates` | `documents:read` | The VAT rates. |
+| `create_estimate_draft` | `documents:write` | Make a draft estimate. Numbering and sending stay in the app. |
+| `update_estimate_draft` | `documents:write` | Change a draft estimate. |
+| `create_invoice_draft` | `documents:write` | Make a draft invoice. |
+| `update_invoice_draft` | `documents:write` | Change a draft invoice. |
+| `list_payment_pages` | `payment-pages:read` | The payment pages. |
+| `get_payment_page` | `payment-pages:read` | One payment page. |
+| `create_payment_page` | `payment-pages:write` | Make a payment page. |
+| `update_payment_page` | `payment-pages:write` | Change a payment page. |
+| `list_email_templates` | `email-templates:manage` | The e-mail templates. |
+| `get_email_template` | `email-templates:manage` | One e-mail template. |
+| `create_email_template` | `email-templates:manage` | Save a new e-mail template. Never sends one. |
+| `update_email_template` | `email-templates:manage` | Change an e-mail template. |
+| `list_tasks` | `tasks:read`, or `projects:read` with `projectId` | Tasks outside projects; with `projectId`, the tasks of that project as the person behind the key sees them. |
+| `get_task` | `tasks:read`, or `projects:read` with `projectId` | One task. |
+| `create_task` | `tasks:write`, or `projects:write` with `projectId` | Make a task on a contact, a deal or nothing; with `projectId`, a task in that project in the person's name. |
+| `update_task` | `tasks:write`, or `projects:write` with `projectId` | Change or complete a task. |
+| `list_projects` | `projects:read` | Projects, groups and events the person behind the key sees. |
+| `get_project` | `projects:read` | One of them. |
+| `list_milestones` | `projects:read` | A project's milestones, in its own order. |
+| `list_time_entries` | `time:read` | The person's hours in a period of at most 92 days, or a colleague's as far as they may read those. |
+| `list_project_services` | `time:read` | What hours can be written on in a project: its services and hour types. |
+| `add_time_entry` | `time:write` | Write an hour of the person, at the service's rate. |
+| `update_time_entry` | `time:write` | Change one of the person's own hours; one on an invoice line stands. |
+| `get_budget_report` | `time:read` | A project's budget per service, as the person's own screen reads it. |
+| `list_project_channels` | `project-messages:write` | The group chats and channels chosen for the key. Names and ids, never messages. |
+| `post_project_message` | `project-messages:write` | Post in a chosen channel, in the person's name. Mails the others in it, customers included. |
+| `list_project_folders` | `project-files:write` | A project's folders, to upload into. |
+| `upload_project_file` | `project-files:write` | Upload a file from this machine to a project. Never a secret-looking file. |
+| `list_appointments` | `calendar:read` | Appointments outside projects, in a window of at most 92 days. |
+| `get_appointment` | `calendar:read` | One appointment outside a project. |
+| `upsert_calendar` | `calendar:manage` | Make or change a calendar by its slug: `event`, `round_robin`, or the account's own services calendar. |
+| `set_calendar_availability` | `calendar:manage` | A calendar's weekly hours and its exceptions per date. |
+| `upsert_services` | `calendar:manage` | Up to fifty bookable services by slug; one nobody performs gets the account's owner. |
+| `site_builder_list_sites` | `sites:read` | The account's websites with their pages (id, path, language, published or not). |
+| `site_builder_read_page` | `sites:read` | A page's draft as a tree of elements with ids; `includeCatalogue` adds the element types, style properties and design tokens. |
+| `site_builder_edit_draft` | `sites:write` | Up to 100 targeted operations on a page's draft by element id: insert, delete, move, update, replace. The draft only. |
+| `site_builder_html_to_draft` | `sites:write` | HTML with a style block turned into sections of a page's draft. The draft only. |
+| `list_client_accounts` | `clients:manage` | The customer accounts a reseller sold, with their owner and modules. |
+| `get_client_account` | `clients:manage` | One of them. |
+| `create_client_account` | `clients:manage` | A customer account with a workspace of its own and a mail to its owner; the same owner twice makes nothing. |
+| `set_client_modules` | `clients:manage` | The modules a customer account is sold with, within what the reseller may hand out. |
+
+### Projects: the key acts as its person
+
+Projects differ per person: who sees a members-only project, a task only for
+a group's leads, a colleague's hours. So every project tool acts as the
+person behind the key -- whoever made it, or approved the connected app --
+and sees and may exactly what that person sees and may in the app. What it
+makes (a task, an hour, a message, a file) is in that person's name, shown
+in the app as "via <name of the key or app>". The tools never make or change
+a project itself, its members or who sees it; they read no conversation and
+open, share, move or delete no file. A message goes only to the channels
+chosen for the key in the app, and mails the others in the channel.
 
 Every catalogue tool takes an optional `object`: the slug of another catalogue
 of the account (from `list_catalogs`). Left out, it is the account's own.
 
+## Only on the online server
+
+The knowledge base follows the rights of a person: who reads a category
+depends on its audience, its groups and the people it is shared with. A key
+has no person, so this server, which runs on a key, does not have these tools
+and the API refuses a key on their routes. They are on the app's online server
+(`/api/mcp`), where an app such as a Claude connector is connected through
+OAuth as the person who approved it.
+
+| Tool | Scope | What it does |
+| --- | --- | --- |
+| `list_kb_categories` | `knowledge-base:read` | The categories the person sees, where they may write, who reads each and whether the website chat answers from it |
+| `search_kb` | `knowledge-base:read` | Articles found by meaning in their title and text, with the piece that matched |
+| `list_kb_articles` | `knowledge-base:read` | Articles, in one category or all; a search on title and summary |
+| `get_kb_article` | `knowledge-base:read` | One article's text as HTML, its status and its version |
+| `create_kb_article` | `knowledge-base:write` | A new article, always a draft |
+| `update_kb_article` | `knowledge-base:write` | A new title, summary or text, at the version that was read |
+| `create_kb_category` | `knowledge-base:write` | A new category that only the team reads, with or without the website chat |
+
+A category made here is always for the team alone; making it public, or
+switching the website chat for a category that already exists, stays in the
+app. `search_kb` embeds the question on Bedrock in Frankfurt and searches by
+words alone, and says so, when that does not answer.
+
+Publishing, taking offline, moving and deleting stay in the app; a published
+article whose text is changed here is live at once. Every change is a new
+version of the article's document, in the person's name. An article somebody
+has open in the editor answers `article_in_use` until they close it.
+
+## Customer accounts for a reseller
+
+A key of a reseller with `clients:manage` sets up the accounts it sells:
+`create_client_account`, `set_client_modules`, and for booking
+`upsert_calendar`, `set_calendar_availability` and `upsert_services` through
+that customer's own key. **A key for a customer is never made by a tool**:
+whatever a tool answers lands in the agent's transcript. A script makes it
+with the client package and hands it straight to where it is kept:
+
+```ts
+const key = await client.createClientApiKey(clientAccountId, {
+  name: 'Website',
+  scopes: ['website:manage', 'forms:manage', 'calendar:manage'],
+});
+// key.token exists only here: pass it on, never print it.
+```
+
 ## After an update
 
 An agent keeps the tool definitions it was handed when its session began, and a