symbiont-mcp

AST-aware code navigation, refactoring engine, and architectural rule checker for the Model Context Protocol (MCP).

Features

• AST file outlines (get_file_outline): inspect functions, classes, methods, interfaces, types, and variables with line ranges and type signatures.

• Symbol tracing (find_all_usages): resolve definitions, call sites, imports, and type references across codebases using TypeScript compiler bindings.

• AST renaming (rename_symbol): rename symbols across referencing files with unified diff generation and dry-run support.

• Architectural invariant checking (check_architecture_rules): validate import boundaries and return-type contracts against .symbiontrc.yaml.

• Dependency graph generation (get_dependency_graph): map module import trees and detect circular dependency cycles.

Related MCP server: Synapse

Installation

git clone https://github.com/DRNZY/symbiont-mcp.git
cd symbiont-mcp
npm install
npm run build

MCP configuration

Add to your MCP configuration file (mcp_config.json or client settings):

{
  "mcpServers": {
    "symbiont": {
      "command": "node",
      "args": ["/path/to/symbiont-mcp/dist/index.js"]
    }
  }
}

Tools reference

• get_file_outline: filePath: string, workspaceRoot?: string

• find_all_usages: symbolName: string, entryFile?: string, workspaceRoot?: string

• rename_symbol: oldName: string, newName: string, targetFile: string, line?: number, dryRun?: boolean, workspaceRoot?: string

• check_architecture_rules: configPath?: string, workspaceRoot?: string

• get_dependency_graph: workspaceRoot?: string

• set_workspace_root: workspaceRoot: string

Configuration (.symbiontrc.yaml)

rules:
  - id: no-db-in-ui
    from: "src/components/**"
    disallow_imports:
      - "src/server/db/**"
      - "drizzle-orm"
      - "@prisma/client"
    message: "UI components must not import directly from the database layer."
    severity: error

  - id: enforce-zod-actions
    files: "src/actions/**"
    require_named_export_type: "z.infer<*>"
    message: "Server actions must return a z.infer typed result."
    severity: warning

  - id: disallow-cycles
    files: "src/**"
    disallow_circular_dependencies: true
    message: "Circular dependency detected."
    severity: error

CLI usage

# Check architecture rules
symbiont-mcp check [.symbiontrc.yaml]

# Inspect symbol outline
symbiont-mcp outline src/components/Button.tsx

# Trace usages
symbiont-mcp usages calculateTotal

# View dependency graph
symbiont-mcp graph

Testing

npm test

License

MIT