Carbon Forge

List atoms in the current workspace. The `path_prefix`, `body_contains`, `metadata`, `sort`, `direction` and `include_metadata` arguments mirror the same arguments on pages.list.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "atoms.list",
    "arguments": {}
  }
}

Read an atom by path or UUID with usage_pages projection. Returns metadata. Pass `section` with a heading's plain text to get back only that heading and the blocks under it, down to the next heading at the same or shallower level; the result then also carries `section: { heading, level, matches }`, and everything else on it is the atom's own, so a section can be read and written straight back.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "atoms.read",
    "arguments": {
      "pathOrId": "..."
    }
  }
}

List the comment thread for a page or atom.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "comments.list",
    "arguments": {
      "target_kind": "page",
      "target_pathOrId": "..."
    }
  }
}

Orientation surface: instance metadata, both grounding documents, identity and capabilities, reachable workspaces, sidecar health. Pass `workspace` to ground a named workspace without moving the per-token pointer. Pass a `known_grounding_at` / `known_workspace_grounding_at` you hold and an unchanged document is acknowledged, not resent. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "cortex.ground",
    "arguments": {}
  }
}

Browse pages or atoms inside a workspace with faceted filters (tag, author, date range, visibility, metadata containment) and sort by alphabetical, recency, or star count. Viewer-aware: members see everything, anonymous callers see only public entities in public workspaces. 50 items per page, cursor-based. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "discovery.list_entities",
    "arguments": {
      "kind": "page"
    }
  }
}

List instances. Filter: all (default) | public | my | my_admin. public lists an instance that has public reading on, is listed in Discover, is not frozen, and has a workspace that is not private holding a page that is not private. my and my_admin list the caller's own instances (member; admin) with no such gate; all is public plus my. Without a token every filter is public.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "discovery.list_instances",
    "arguments": {}
  }
}

List workspaces across one or all instances, with the same filters. public lists a workspace when its instance has public reading on, the workspace is not private, its instance is listed in Discover and not frozen, and it holds a page that is not private. my and my_admin list the caller's own workspaces with no such gate; all is public plus my. Without a token every filter is public.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "discovery.list_workspaces",
    "arguments": {}
  }
}

Search instance and workspace metadata + grounding documents. Returns parallel lists for both scopes.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "discovery.search",
    "arguments": {
      "q": "..."
    }
  }
}

Browse the workspace as a file tree, one level at a time: directories, pages, atoms, code trees (expanded at their paths) and library entries. Each node names its kind, entity, current revision and digest; `at` holds the entities exactly at `path`. `surface` keeps that surface only. History: files.history. Anonymous callers see public pages and atoms, and code trees of surface code.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "files.list",
    "arguments": {}
  }
}

Semantic nearest-neighbors via similarity_edges.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "kg.get_related",
    "arguments": {
      "pathOrId": "...",
      "kind": "page"
    }
  }
}

List incoming + outgoing cross-links for a page or atom.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "kg.list_cross_links",
    "arguments": {
      "pathOrId": "...",
      "kind": "page"
    }
  }
}

Fetch metadata for a single media item.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "media.read",
    "arguments": {
      "media_id": "..."
    }
  }
}

List pages in a workspace. `path_prefix` narrows by leading segment; `body_contains` keeps pages whose Markdown holds a literal substring; `metadata` keeps pages whose top-level metadata contains the given scalar keys; `sort` (path | updated_at | created_at) and `direction` order the set; `include_metadata` adds each page's metadata. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "pages.list",
    "arguments": {}
  }
}

Read a page by path or UUID. Returns the Markdown body plus the page metadata object. Pass `section` with a heading's plain text to get back only that heading and the blocks under it, down to the next heading at the same or shallower level; the result then also carries `section: { heading, level, matches }`. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "pages.read",
    "arguments": {
      "pathOrId": "..."
    }
  }
}

Markdown-level diff between two revisions of the same page or atom. Returns segments (op: equal | insert | delete) plus both Markdown projections.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "revisions.compare",
    "arguments": {
      "kind": "page",
      "pathOrId": "...",
      "revision_a_id": 0,
      "revision_b_id": 0
    }
  }
}

Fetch a specific revision (returns Markdown body).

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "revisions.get",
    "arguments": {
      "kind": "page",
      "pathOrId": "...",
      "revision_id": 0
    }
  }
}

List revisions for a page or atom (cursor-paginated).

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "revisions.list",
    "arguments": {
      "kind": "page",
      "pathOrId": "..."
    }
  }
}

Hybrid FTS + pgvector + RRF search. Returns Markdown excerpts.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "search.global",
    "arguments": {
      "q": "..."
    }
  }
}

Exact-substring search over the Markdown projection of pages and atoms — deterministic, unlike hybrid `search.global`. A needle shorter than 3 characters is rejected. Returns one envelope per matched entity, up to 5 hits each as `{ line, col, snippet }`. `case_sensitive` defaults to false; `scope` is workspace | all_mine | all_public. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "search.literal",
    "arguments": {
      "q": "..."
    }
  }
}

Read a code tree's revision (the current one by default), its metadata and surface, and a page of its entries in path order: path, git mode, size and blob SHA-256, optionally under `path_prefix`. A symlink's blob is its target; a submodule link has no blob and gives its `commit`. With `lane`, `metadata` is the lane's bag if it sets one. Anonymous callers read a public code tree's current one.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "trees.get",
    "arguments": {
      "path_or_id": "..."
    }
  }
}

List every workspace the calling user is a member of. This is a membership catalogue and not a capability: it is not narrowed by the token, so a listed workspace may still be outside this token's reach. Call cortex.ground for what this token can actually resolve.

Takes no parameters.

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "workspaces.list",
    "arguments": {}
  }
}

Resolve a workspace slug to its id, role, and archived state. 404 when the caller isn't a member (no enumeration).

Example call (required arguments only, placeholder values):

{
  "method": "tools/call",
  "params": {
    "name": "workspaces.resolve_slug",
    "arguments": {
      "slug": "..."
    }
  }
}