cerebro-knowledge repo

TL;DR — securitize_dev/cerebro-knowledge is the Bitbucket repo that backs the cerebro MCP. It packages four artifact types (skills, workflows, wiki, services catalog) into a single content store. The MCP picks one branch via the SEC_MCP_BITBUCKET_BRANCH env var — by default master, but it can be pointed at any branch to preview unmerged changes locally.

Overview

The cerebro MCP server (@securitize/cerebro-mcp) reads its content live from the cerebro-knowledge Bitbucket repo. Every get_skill_file, get_workflow_file, get_wiki_file, and get_catalog_index call resolves to a file in this repo on the branch that the MCP was configured to follow.

Source for the MCP package itself: securitize_dev/commons-shared/packages/cerebro-mcp — see its README/AGENTS.md for the full server-side details (caching, file resolution, error modes).

What lives in cerebro-knowledge

The repo packages four kinds of artifact, each served through distinct MCP tools:

Folder	Content type	Served by
skills/	Declarative coding standards	get_skill_file / list_skills
workflows/	Imperative operational playbooks	get_workflow_file
wiki/	Declarative facts about Securitize	get_wiki_file
services/	Auto-generated microservice catalogs	get_service_catalogs / get_endpoint_contracts / get_catalog_index

The distinction matters when deciding where a new piece of content belongs.

Skills (skills/)

Declarative coding principles — the rules for how Securitize writes code on a given stack.

• Example: "In NestJS, controllers delegate to services."
• Use when: documenting a per-technology standard, framework convention, language idiom, or review rubric.
• Don't use when: the content is a procedure to execute (→ workflow) or a Securitize-specific fact (→ wiki).

Workflows (workflows/)

Imperative operational procedures — numbered steps to execute.

• Example: "1. Clone ops-scripts. 2. Edit the file. 3. Open a PR. 4. Trigger the Jenkins job."
• Use when: there is a multi-step task with a concrete start, middle, and end (configure DNS, rotate a token, update a ConfigMap, generate a local config file).
• Don't use when: the content is a principle to apply (→ skill) or just a fact to look up (→ wiki).

Wiki (wiki/)

Declarative facts about Securitize — the SSOT for every reference value used elsewhere.

• Example: "The DEV AWS account ID is 766597584338." "Internal services use <svc>.internal.<env>.securitize.io."
• Use when: documenting an account ID, URL pattern, env-by-env table, ownership map, infrastructure topology, or any reference value that multiple skills/workflows will need to link to.
• Don't use when: the content is a coding rule (→ skill) or a procedure (→ workflow).

Services catalog (services/)

Auto-generated catalog of every Securitize microservice and its API endpoints. Do not hand-edit — files here are regenerated from each service's OpenAPI spec.

• Use when: looking up which service exposes which endpoint, or what a service's API contract is.
• Don't edit by hand: any manual change is overwritten on the next regeneration.

Quick test

• Numbered steps to execute → workflow.
• A rule or principle → skill.
• A fact that other content will reference → wiki.

Where authoring conventions live

This page covers what each artifact is and when to use it — enough to decide where a change belongs and have a productive conversation before cloning the repo. The full authoring rules (YAML frontmatter shape, file templates, index.md maintenance, SSOT enforcement, English-only tone, validation checks) live in AGENTS.md at the root of the cerebro-knowledge repo. Read it after cloning, before writing the change — AGENTS.md is not served through the MCP, so the local copy is the only way to consult it.

MCP integration

Package: @securitize/cerebro-mcp (npm, published from commons-shared).

Required env vars

Env var	Purpose	Typical value
NPM_CONFIG_//registry.npmjs.org/:_authToken	Auth to install the package from the Securitize private npm	The dev's SECURITIZE_READ_NPM_TOKEN (see secrets.md)
SEC_MCP_BITBUCKET_WORKSPACE	Bitbucket workspace	securitize_dev
SEC_MCP_BITBUCKET_REPO_SLUG	Bitbucket repo slug	cerebro-knowledge
SEC_MCP_BITBUCKET_USERNAME	Bitbucket user (email)	<your-email>@securitize.io
SEC_MCP_BITBUCKET_API_TOKEN	Atlassian API token (NOT account password)	Generated at id.atlassian.com/manage-profile/security/api-tokens
SEC_MCP_SKILLS_PATH	Folder under repo root to serve as skills	skills
SEC_MCP_BITBUCKET_BRANCH	Which branch of the repo the MCP serves	master (default) — see "Branch override" below

Standard config block

The JSON shape is the same across every MCP-compatible agent — the only thing that changes is where the file lives. Add the cerebro entry to the mcpServers object of your agent's MCP config:

Agent	Default config path
Claude Code	~/.claude.json (user-level) or .mcp.json (project-level)
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (user)
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline / Continue / other VS Code-based agents	Each agent's own settings — see its docs

If your agent is not listed, check its docs for "MCP server configuration"; the mcpServers.<name> shape is the MCP standard.

{
  "mcpServers": {
    "cerebro": {
      "command": "npx",
      "args": ["-y", "@securitize/cerebro-mcp@latest"],
      "env": {
        "NPM_CONFIG_//registry.npmjs.org/:_authToken": "<your-securitize-npm-token>",
        "SEC_MCP_BITBUCKET_WORKSPACE": "securitize_dev",
        "SEC_MCP_BITBUCKET_REPO_SLUG": "cerebro-knowledge",
        "SEC_MCP_BITBUCKET_USERNAME": "<your-email>@securitize.io",
        "SEC_MCP_BITBUCKET_API_TOKEN": "<your-atlassian-api-token>",
        "SEC_MCP_SKILLS_PATH": "skills",
        "SEC_MCP_BITBUCKET_BRANCH": "master"
      }
    }
  }
}

SEC_MCP_BITBUCKET_API_TOKEN is an Atlassian API token

Use an Atlassian API token (generated at https://id.atlassian.com/manage-profile/security/api-tokens) — not your Bitbucket/SSO password.

Branch override for local testing

SEC_MCP_BITBUCKET_BRANCH is a free-form branch name. Setting it to any branch in cerebro-knowledge makes the MCP serve content from that branch instead of master — useful for previewing a PR's content end-to-end before merge.

How to swap (same procedure for every MCP-compatible agent — only the config file path varies; see the table in "Standard config block" above):

1. Open your agent's MCP config file. Locate the cerebro entry and change the SEC_MCP_BITBUCKET_BRANCH value to the branch you want to test.
2. Restart the agent (or reload the MCP server through whatever mechanism the agent provides). The MCP server reads the env var at startup; in-flight changes are not picked up.
3. Verify with a get_workflow_file / get_wiki_file call that returns content from your branch.
4. When done, set it back to master and restart the agent again.

Use branch names without slashes

Conventional Git branch names like feature/foo work fine inside Bitbucket, but the / is awkward when the branch name lives inside a JSON env value (escaping, shell quoting, copy-paste). Use a flat hyphen-separated name (e.g. workflow-update-cerebro-knowledge) for any branch you intend to test through the MCP. Branches in this repo standardize on flat names for that reason.

Contributing changes

Every change to cerebro-knowledge follows the same procedure regardless of artifact type. Use the update-cerebro-knowledge workflow — it walks you through clone, branching, conventions (which it links back to AGENTS.md), optional local test via the branch override above, and PR opening with default reviewers.

The conventions for what to write (skill structure, wiki frontmatter, workflow template, SSOT rules, tone, English-only) are all in AGENTS.md at the repo root. Read it before writing or editing anything in this repo.

See also

• MCP Servers & AI Tooling — the broader MCP landscape; cerebro is one of six.
• Secrets — where the SECURITIZE_READ_NPM_TOKEN used in the config lives.
• update-cerebro-knowledge workflow — the contribution procedure.

Tags

cerebro #mcp #knowledge-base #contribution #cerebro-knowledge