Skip to content

feat(mcp): add configurable AI role/system prompt support (#1320) - #1733

Draft
yashraj4 wants to merge 2 commits into
CodeGraphContext:mainfrom
yashraj4:feature/mcp-role-prompt
Draft

yashraj4 wants to merge 2 commits into
CodeGraphContext:mainfrom
yashraj4:feature/mcp-role-prompt

Conversation

@yashraj4

@yashraj4 yashraj4 commented Sep 24, 2026 •

Copy link
Copy Markdown

Closes #1320

Injection point decision

The role is injected into the MCP \initialize\ response — specifically both the \instructions\ field and \serverInfo.systemPrompt\ field. This is the standard MCP mechanism for system-level instructions.

Why this point:

  • It is sent once at connection time, not per tool call — no per-request overhead
  • It does not touch tool descriptions (\ tools/list\) or tool results (`\ tools/call) — zero blast radius on the 25+ existing tools
  • MCP clients (Claude, Cursor, Copilot) already read \instructions\ from \initialize\
  • When no role is configured, both fields are byte-identical to current behaviour

What was built

CLI options on \cgc mcp start\

\
--role reviewer | architect | auditor | explainer | custom | neutral
--role-file Path to a custom role .md file (max 64 KB)
\\

Built-in roles (\src/codegraphcontext/roles/)

  • \ reviewer.md\ — senior code reviewer persona
  • \architect.md\ — software architect persona
  • \editor.md\ — dead code/risk auditor persona
  • \explainer.md\ — code onboarding/documentation persona
  • Neutral (default) — no injection at all

Precedence (stated once, tested)

  1. --role\ CLI flag
  2. \CGC_MCP_ROLE\ environment variable

  3. ole\ key in .cgc/config.json\
  4. Built-in default: none (no injection)

--role-file\ overrides the content source regardless of which role name was selected. Without an explicit --role, it implies \custom.

Role file validation

  • Size cap: 64 KB (\MAX_ROLE_FILE_BYTES) — rejected with clear message
  • Must be a regular file — directories rejected with clear message
  • Path sandbox: subject to \is_path_allowed()\ from \utils/path_sandbox.py, with ~/.codegraphcontext/\ always allowed as the documented config directory
  • **\CGC_ALLOW_ALL_PATHS**: honoured if present (forward-compatible with feat(security): allow disabling path sandbox via CGC_ALLOW_ALL_PATHS #1726)
  • Empty/whitespace-only files rejected

Byte-identical default (the critical invariant)

With no role configured:

  • \b�uild_system_prompt()\ returns exactly \LLM_SYSTEM_PROMPT\
  • \instructions\ field equals exactly \LLM_SYSTEM_PROMPT\
  • \serverInfo.systemPrompt\ equals exactly the pre-feature output

  • esolve_role_prompt()\ returns \None\

Tested by: \TestUnconfiguredByteIdentical\ (5 tests asserting byte equality).

Files changed

File Change
\src/codegraphcontext/roles/init.py\ Role resolution, loading, validation
\src/codegraphcontext/roles/{reviewer,architect,auditor,explainer}.md\ Built-in role definitions
\src/codegraphcontext/prompts.py\ \�uild_system_prompt()\ accepts \
ole_prompt\ param
\src/codegraphcontext/server.py\ \MCPServer\ accepts \
ole_prompt, uses in \initialize\
\src/codegraphcontext/cli/main.py\ --role\ and --role-file\ options on \mcp start\
\pyproject.toml, \MANIFEST.in\ Include \
oles/*.md\ as package data
\ ests/unit/test_mcp_roles.py\ 30 tests

Test results

\
30 passed in 1.45s
\\

Covers: byte-identical default, role injection, size cap, directory rejection, missing file, empty file, path sandbox, \CGC_ALLOW_ALL_PATHS, precedence (CLI > env > config > default), unknown role error, all built-in roles load.

…tool

- Add index_dependencies parameter to add_code_to_graph tool schema in tool_definitions.py
- Implement _collect_python_imports() using ast module to extract top-level import names
- Implement _filter_and_resolve_dependencies() to filter stdlib/local modules and resolve external packages
- Modify add_code_to_graph() in indexing_handlers.py to queue dependency indexing jobs when index_dependencies=True
- Add comprehensive unit tests in tests/unit/tools/test_index_dependencies.py

Co-authored-by: yashraj4
…ontext#1320)

Add --role and --role-file options to 'cgc mcp start' that inject a
role-specific system prompt into the MCP initialize response.

Injection point: the initialize response's 'instructions' field and
'serverInfo.systemPrompt' field. When no role is configured both fields
are byte-identical to the current behaviour.

Built-in roles: reviewer, architect, auditor, explainer.
Custom roles: --role custom (reads ~/.codegraphcontext/role.md) or
--role-file <path>.

Precedence: --role > CGC_MCP_ROLE env > .cgc/config.json > neutral.
Role files are validated: max 64 KB, must be regular files, subject to
path sandbox with ~/.codegraphcontext/ always allowed.

30 unit tests covering byte-identical default, injection, size cap,
path sandbox, and precedence.
@vercel

vercel Bot commented Sep 24, 2026

Copy link
Copy Markdown

@yashraj4 is attempting to deploy a commit to the shashankss1205's projects Team on Vercel.

A member of the Team first needs to authorize it.

@Shashankss1205 Shashankss1205 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Role prompt feature is still draft; review config path restrictions and distribution/package behavior before marking ready.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog tasks

Development

Successfully merging this pull request may close these issues.

Add configurable AI role/system prompt support for MCP server

2 participants