Skip to main content
Glama
aidemd-mcp

aidemd-mcp/server

by aidemd-mcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

aide_brain

Fetch .aide brain config sections on demand, inspect template and contract details, validate draft files, and guide setup or repair one step at a time.

Instructions

On-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily. It is also how a brain config is set up, repaired or written for any backend, one decision at a time. Every mode is read-only: no call writes to disk.

Optional source parameter — which read runs. Omitted means "host".

  • "host" — one section of the host's .aide/config/brain.aide, described below.

  • "template" — { template, purpose }: one section of the bundled template (or its launcher, with kind: "launcher") as verbatim bytes, and that section's one-line purpose from the published contract. The answer is the same whatever state the host's config is in. Use it as a worked example when writing that section for another backend.

  • "contract" — { sections }: every contract section in order, each with marker, role (live or seed) and purpose, and no section text.

  • "draft" — a structural check of the draft config at path, with the same rules and fault vocabulary as the host config check, so a draft that passes is ready to swap in. Returns { outcome, instructions }: valid; invalid with fault (missing-sections and its sections, or malformed and its reason); absent when no file is at path; refused when path is outside the project, and nothing is read. It checks structure, never content.

Optional kind parameter — host and template reads only: any section marker of the published brain contract (see the enum), live or seed; "launcher" only with source: "template". Omitting it means "orientation", the runtime briefing for reaching the brain mid-task. "config" is the integration's wiring flow that /aide:brain config runs. Seed sections are fetched one per call while seeding. path is required with source: "draft" and accepted nowhere else; any other combination is rejected before the tool runs.

Host read response shape: exactly { status, instructions, found, purpose? }. No backend, no connector, no name, no kind.

  • found: true — instructions is that section's verbatim bytes from the host's .aide/config/brain.aide: no trimming, no normalization, no ${...} substitution. purpose is that section's one-line purpose from the published contract; use it when adapting the section for another backend.

  • found: false — instructions is remediation, and purpose is absent. An absent file → run /aide:brain config. A requested section missing from the file → with the user's consent, call aide_upgrade with category: "brain". A malformed or unreadable file → the exact fault, a hand fix with the user, then re-check with aide_info. Do not proceed as if the section were available.

The section is returned on every status where the config exists and is well-formed, including brain-aide-invalid with missing sections, no-mcp-entry and mcp-drift.

status mirrors the BrainState tagged union from buildBrainState, with five values: ok, no-brain-aide, brain-aide-invalid, no-mcp-entry, mcp-drift. Branch on found for "did I get the section" and on status for "is the brain healthy".

Input Schema

NameRequiredDescriptionDefault
kindNoWhich section: any section marker of the published contract, live or seed, or `launcher` with `source: "template"` only. Omitted means `orientation`. Not accepted with `contract` or `draft`. Seed sections are fetched one per call while seeding.
pathNoProject-relative path of a draft brain config. Required with `source: "draft"` and accepted nowhere else; a path outside the project is refused unread.
sourceNoWhich read runs. Omitted means `host`: one section of the host's `.aide/config/brain.aide`. `template`: one section or the launcher of the bundled template, with its purpose. `contract`: every contract section with its role and purpose. `draft`: a structural check of the draft config at `path`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.11.1
    • changedInput schema / properties / kind / description
      Previous value: -"Which section of brain.aide to return. `\"orientation\"` (default when omitted) returns the runtime briefing for mid-task brain access. `\"config\"` returns the integration-specific wiring flow used by `/aide:brain config`."New value: +"Which section: any section marker of the published contract, live or seed, or `launcher` with `source: \"template\"` only. Omitted means `orientation`. Not accepted with `contract` or `draft`. Seed sections are fetched one per call while seeding."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "orientation",
-  "config"
-]New value: +[
+  "orientation",
+  "config",
+  "playbook-index",
+  "study-playbook",
+  "update-playbook",
+  "research-index",
+  "kanban-index",
+  "kanban-create",
+  "kanban-work",
+  "kanban-manage",
+  "kanban-move",
+  "kanban-complete",
+  "kanban-stash",
+  "kanban-review",
+  "launcher"
+]
    • addedInput schema / properties / path
      Added value: +{
+  "description": "Project-relative path of a draft brain config. Required with `source: \"draft\"` and accepted nowhere else; a path outside the project is refused unread.",
+  "type": "string"
+}
    • addedInput schema / properties / source
      Added value: +{
+  "description": "Which read runs. Omitted means `host`: one section of the host's `.aide/config/brain.aide`. `template`: one section or the launcher of the bundled template, with its purpose. `contract`: every contract section with its role and purpose. `draft`: a structural check of the draft config at `path`.",
+  "enum": [
+    "host",
+    "template",
+    "contract",
+    "draft"
+  ],
+  "type": "string"
+}
  2. Addedv0.6.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and succeeds: it declares 'Every mode is read-only: no call writes to disk', documents the exact host response shape, enumerates all five status values, and explains that 'draft' never reads content and refuses paths outside the project. These are behaviors the agent could not infer from the schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and usage caveat, then organized by parameter and response shape with bold headers and bullets. It is long and partially restates the schema's enum descriptions, but nearly every sentence carries operational detail (status values, fault vocabulary, remediation branches) rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must define returns — and it does, giving the exact host response shape, found:true/false semantics, the four draft outcomes, and the contract/template payload shapes. Nothing an agent needs to call this correctly or interpret its result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters and their enums; the baseline would be 3. The description goes further by specifying per-source response shapes, the 'source: draft requires path' constraint, and the incompatibility of path with any other source, though it retreads some enum text already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource — an on-demand entry point that reads brain sections — and explicitly separates itself from siblings by contrasting with aide_info.brain.status (boot-time reporting) and naming aide_upgrade for remediation. An agent can identify what this tool does and what it is not without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not ('do NOT call it on every /aide boot') with the reason, plus a named alternative for boot state. It also routes to /aide:brain config, aide_upgrade, and aide_info for specific failure cases, so the agent has a decision path for almost every scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools