@awesomate/hosting-mcp
Version:
Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases
225 lines (194 loc) • 13.8 kB
Markdown
# The 1Brain node: workflows and AI agents that use 1Brain
1Brain (Business Blueprint) holds the business's systems: policies, procedures
(SOPs), training courses, quizzes and acknowledgements. The 1Brain node reads
and writes them from a workflow, or gives an AI Agent node tools to answer from
them. For what 1Brain is, connecting it, and the rules that apply on every
route (drafts, explicit account, never invent SOP content, page links in every
answer), load the **awesomate-onebrain** skill too.
## 0. Before you design anything
1. **`features.onebrain`** in `awesomate_get_context`: `available: false` means
say its `message` in one line and stop.
2. **Is the node on this instance?** It ships in fleet image
`2.41.4-awesomate.10` and later, which only some instances run so far; the
rest get it with the next fleet image. Check:
- `awesomate_n8n_inspect {what:'credentials'}`: a `oneBrainApi` credential
("1Brain - <person>") means the node is there (the hub can only place it on
an instance that knows the type).
- `awesomate_n8n_inspect {what:'nodes'}`: `CUSTOM.oneBrain` or
`CUSTOM.oneBrainTool` already in use means it is there.
- Neither: assume it is not, or ask Awesomate support whether the account's
n8n has the 1Brain node yet. Say
so, and offer the MCP Client Tool route (section 6), which needs only
core n8n (not yet proven end to end: say so).
3. **Whose credential?** Each person who connected 1Brain in the hub has their
own "1Brain - <person>" credential. No credential: they connect first
(hub Settings, Integrations, 1Brain). For an agent, use the credential of
the person the agent answers to (its supervisor): the agent can never see
more than that person.
4. **Validation false positive:** `awesomate_n8n_node_docs validate_node`
does not know CUSTOM nodes and reports the 1Brain
node as unknown. Expected; do not "fix" it. The node catalog has no schema
for it either: this page is the reference.
## 1. Node types and credentials
| | |
|---|---|
| Regular node | `CUSTOM.oneBrain` |
| AI Agent tool | `CUSTOM.oneBrainTool` (connect to the agent's `ai_tool` input) |
| typeVersion | `2` for anything new. Version 1 exists only so old workflows open |
| Authentication `accessToken` (default) | Credential `oneBrainApi` (fields `accessToken`, `baseUrl`). Made and kept current by the hub, one per person. Never create or edit it |
| Authentication `oAuth2` | Credential `oneBrainOAuth2Api`: n8n signs in to 1Brain itself. Only for n8n instances the hub does not manage |
| Base URL | `https://dev.1brain.io` until 1Brain's production connection is live. Only https `1brain.io`, `1brain.app` or `1brain.it` hosts are accepted |
Parameters: `resource`, `operation`, `businessId` (the 1Brain account id, on
every operation except Tool > Call, where it is optional), then the operation's
own fields. Optional fields sit in `additionalFields`. A Page Search as an
agent tool:
```json
{
"name": "Search procedures",
"type": "CUSTOM.oneBrainTool",
"typeVersion": 2,
"position": [600, 400],
"parameters": {
"authentication": "accessToken",
"businessId": 1234,
"resource": "page",
"operation": "search",
"query": "={{ $fromAI('query', 'Words to search the business procedures for', 'string') }}",
"limit": 5
},
"credentials": {
"oneBrainApi": { "id": "<id from awesomate_n8n_inspect credentials>", "name": "1Brain - Sam Taylor" }
}
}
```
Get the account id from an Account > Get Many run (or the dropdown in the
editor). Page Get takes `pageId` (a number). Department fields are
`departmentId`, category fields `categoryId`; folder fields are a resource
locator (`{ "__rl": true, "mode": "id", "value": "415331" }`, or `mode: "title"`).
## 2. Operations
| Resource | Operation (`resource` / `operation`) | What it does | Who can |
|---|---|---|---|
| Account | Get Many (`account` / `getMany`) | Accounts this connection may use, with their categories | anyone |
| Account | Set Active (`account` / `setActive`) | Make an account the default. Rarely needed: the node names the account on every call | anyone |
| Page | **Search** (`page` / `search`, the default) | Full-text search over titles, content and video transcripts, drafts included | anyone |
| Page | Get (`page` / `get`) | One page: plain text, HTML, videos and transcripts | anyone with access |
| Page | Get Many (`page` / `getMany`) | Every page in a department, folder or category, drafts included | anyone |
| Page | Create (`page` / `create`) | A page in a department, optionally in a folder | editors |
| Page | Update (`page` / `update`) | Title or description of a page or folder (not its contents) | its creator |
| Page | Publish (`page` / `publish`) | Publish the latest draft (policies go to review) | its creator |
| Page | Publish Many (`page` / `publishMany`) | Every unpublished page in a scope, 25 per call | its creator |
| Page | Share (`page` / `share`) | Turn on public sharing and return the link | its creator |
| Page | Add Tags (`page` / `addTags`) | Add tags to a page or folder (folder tags reach its pages) | editors |
| SOP | Save (`sop` / `save`) | Save SOP or policy HTML you wrote, as a new page or a new version | editors |
| SOP | Create Many (`sop` / `createMany`) | Up to 25 SOP or policy pages in one call | editors |
| SOP | Tailor (`sop` / `tailor`) | Fit existing pages to the business (find and replace rules, or rewritten HTML) | editors |
| SOP | Get Tailor Progress (`sop` / `getTailorProgress`) | Status of a background tailoring run | anyone |
| SOP | Cancel Tailor (`sop` / `cancelTailor`) | Stop a background tailoring run | editors |
| Category | Get Many (`category` / `getMany`) | Categories, and whether each has a business description | anyone |
| Category | Create (`category` / `create`) | A category, private to its creator until shared | editors |
| Department | Get Many (`department` / `getMany`) | Departments, optionally in one category | anyone |
| Department | Create (`department` / `create`) | A department in a category | editors |
| Department | Update (`department` / `update`) | Name, description, cover | editors |
| Folder | Create (`folder` / `create`) | A folder in a department | editors |
| Image | Upload (`image` / `upload`) | PNG or JPEG (up to 8 MB) from binary data; returns an upload id | editors |
| Image | Add to Page (`image` / `addToPage`) | Put an image at the end of a page | the page's creator |
| Image | Set Department Cover (`image` / `setDepartmentCover`) | Use an image as a department's cover | editors |
| Course | Get Many, Get (`course` / `getMany`, `get`) | Courses and their lessons | anyone who can see them |
| Course | Create (`course` / `create`) | A **published** course from a category, department, folder or chosen pages | owners, admins |
| Quiz | Get Many, Get (`quiz` / `getMany`, `get`) | Quizzes and each member's results | owners, admins |
| Quiz | Create, Delete (`quiz` / `create`, `delete`) | Add a quiz you wrote to a page, or remove it | owners, admins |
| Read Marker | Get Many, Get (`readMarker` / `getMany`, `get`) | Acknowledgements and who completed them | owners, admins |
| Read Marker | Create, Delete (`readMarker` / `create`, `delete`) | Add or remove an acknowledgement on a page | owners, admins |
| Team Member | Get Many (`teamMember` / `getMany`) | Members with name, email and role | owners, admins |
| Tool | Call (`tool` / `call`) | Any 1Brain tool by name (`toolName`) with JSON arguments (`toolArguments`) | depends on the tool |
Search options (`searchOptions`): **Include Content** (`includeContent`: adds
each hit's page text, one extra request per hit), **Limit to Department**
(`department`), **Limit to Folder** (`folder`), and Status and Type filters on
the results. Results carry `id`, `title`, `type`, `status` and `url`; every
answer built from a page ends with its `url`. Search ids come back as strings;
Page Get takes a number (`={{ Number($json.id) }}`).
## 3. Behaviour to design around
- **Drafts by default.** Every write that takes a status defaults to Draft in
the node (1Brain itself defaults to Published). Publish with Page > Publish,
only when the person asked.
- **The account is always explicit.** The node sends it on every call;
otherwise 1Brain uses (and changes) the connection's active account.
- **Permissions are 1Brain's.** A run sees and changes only what the connected
person can. Update, Publish, Share and Add to Page need the page's creator.
- **60 requests a minute per person**, shared by every workflow and agent on
that person's credential. The node retries a 429 itself. Prefer one Get Many
over many Gets; turn Include Content on only for a few hits.
- **Errors are plain.** Access switched off by the 1Brain account's owner
arrives as an error, not a sign-in problem: never "fix" it by reconnecting.
401 means the person connects again in the hub. A login page means the
credential is not signed in. An old operation says "This 1Brain operation was
retired. Open the node and pick a new one."
- **1Brain never writes content.** You (or an LLM step working from the owner's
material) write the HTML. A category with no business description makes the
SOP operations stop and ask for one (`business_description`); SOP Save asks
which template to follow (`sop_template_source`: `1brain` or `user`). Pass
the owner's own words, never invented ones.
- **Tags cannot be read** and **search cannot filter by tag**. Use Limit to
Department or Limit to Folder.
- **Search ranking is loose and returns titles only.** For answers, search,
then read the top pages with Page Get.
## 4. Patterns
### An agent that answers from the business's procedures
Chat Trigger (or a channel) → AI Agent with two `CUSTOM.oneBrainTool` tools,
both on the supervisor's credential and the same `businessId`:
1. **Search procedures**: Page > Search, `query` from `$fromAI`, `limit` 5.
2. **Read a procedure**: Page > Get, `pageId` from
`$fromAI('pageId', 'The id of a page from Search procedures', 'number')`.
System message (adapt, keep the rules): "Answer only from the business's
procedures in 1Brain. Search first, then read the most relevant pages before
answering. If nothing relevant is found, say you couldn't find a procedure for
it and suggest who to ask; never guess. End every answer with the links (url)
of the pages you used." Add the role's `instructionLine` from
`awesomate_business_map` when the agent helps a role. Read-only by design: give
it no write operations unless the owner asks for that, and then make writes
Draft. Test with a question the procedures answer and one they do not.
### A form or email turned into an SOP draft
Trigger (form, email, Slack message) → an LLM step that turns the person's
notes into SOP HTML **using only what they wrote**, marking gaps as questions →
1Brain **SOP > Save** (scope department, `status` draft; or Page > Create with
`status: draft`) → tell the owner, with the page link, that a draft is waiting
for review. Run Category > Get Many once while designing: a category with no
business description needs one from the owner before SOP Save works.
### A weekly report of unpublished drafts
Schedule Trigger → Department > Get Many → Page > Get Many per department
(scope department: one request each, not one per page) → keep `status: draft`
→ one email or message listing each draft's title and link, grouped by
department. See [recurring-reports.md](recurring-reports.md) for the delivery
side. Ten departments is ten requests: well inside 60 a minute.
### Anything not in the operation list
Tool > Call with the 1Brain tool's name (the dropdown lists them live) and its
arguments as JSON. Use it sparingly and keep writes as drafts.
## 5. Old 1Brain workflows (version 1)
Some accounts have workflows from the earlier, pre-Awesomate 1Brain node (one
action, "Search 1Brain"). They open as version 1, Page > Search, with the
account (`businessId`) and `query` kept and page text added by default, as
before. To bring one back to life:
1. Reconnect: pick the person's hub-made "1Brain - <person>" credential. Old
credentials cannot reach 1Brain's new connection.
2. **Remove the tags.** Search can no longer filter by tag, so a version 1 node
with tags stops with a clear message rather than searching the whole
account. Use Limit to Department or Limit to Folder instead.
3. Check the account: an old `businessId` may be a production 1Brain account
that the development server (today's only connection point) does not have.
4. Any other old operation says "This 1Brain operation was retired": pick a new
one in the node.
Change a live workflow on its own id through the n8n MCP server (SKILL.md
§4), tested on a copy first, never by activating a copy in its place.
## 6. The no-code route: MCP Client Tool
For an AI Agent that needs every 1Brain action with no node setup: n8n's own
MCP Client Tool (`/n8n-nodes-langchain.mcpClientTool`; resolve its
parameters with `awesomate_n8n_node_docs`) with the **MCP OAuth2** credential
(`mcpOAuth2Api`), server address `https://dev.1brain.io/mcp`. The person
creates and signs in to the credential on their n8n (it is an OAuth sign-in,
so it is always finished in the browser). n8n 2.41.4's own source supports
it (dynamic client registration, PKCE, rotating refresh tokens), but it has
**not been run end to end yet**: tell the person it is untested, and test it
with them before anyone relies on it. Each reconnect
registers a new 1Brain connection, and the agent can use every tool the person
can, writes included, so its system message must carry the rules above
(drafts, confirm, never invent, links).