Sgraph

Python 3.13+ License: MIT CI

An MCP server that gives AI agents instant access to software architecture, dependencies, and impact analysis through pre-computed sgraph models. One tool call replaces dozens of grep/read cycles.

Why?

AI agents discover code structure by reading files one at a time. For a question like "what calls this function?", that means grep, read, grep again, read again... Dozens of round-trips, thousands of tokens, and results that still miss indirect callers.

SGraph pre-computes the full dependency graph. The same question takes one call and returns every caller with type information.

Quick Start

1. Install

git clone https://github.com/softagram/sgraph-mcp-server.git
cd sgraph-mcp-server
uv sync

2. Start the server

# With Claude Code profile (recommended)
uv run python -m src.server --profile claude-code

# With auto-loaded model (skip the load_model step)
uv run python -m src.server --profile claude-code \
  --auto-load /path/to/model.xml.zip \
  --default-scope /Project/src

3. Connect your AI agent

{
  "mcpServers": {
    "sgraph": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/sgraph-mcp-server",
        "python", "-m", "src.server",
        "--profile", "claude-code",
        "--transport", "stdio",
        "--auto-load", "/path/to/model.xml.zip"
      ]
    }
  }
}

uv run python -m src.server --profile claude-code --transport sse --port 8008

{
  "mcpServers": {
    "sgraph": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8008/sse"]
    }
  }
}

/Project
  /Project/src
    /Project/src/auth/login.py
      /Project/src/auth/login.py/LoginHandler        (class)
        /Project/src/auth/login.py/LoginHandler/validate  (method)
  /Project/External
    /Project/External/Python/requests                 (third-party)

Tools

The claude-code profile provides 6 tools optimized for AI-assisted development:

The key tool is sgraph_get_element_dependencies with its result_level parameter for controlling abstraction:

result_level=None  ->  /Project/src/auth/login.py/LoginHandler/validate  (raw)
result_level=4     ->  /Project/src/auth/login.py                        (file)
result_level=3     ->  /Project/src/auth                                 (directory)
result_level=2     ->  /Project/src                                      (component)

For the full tool reference with workflows and examples, see SGRAPH_FOR_CLAUDE_CODE.md.

uv run python -m src.server --profile legacy

Example Conversation

You: "What would break if I rename the validate() method in auth/login.py?"

Agent calls: sgraph_analyze_change_impact(element_path="/Project/src/auth/login.py/LoginHandler/validate")

Result:
  5 callers in 3 files
  - /Project/src/api/routes.py (2 call sites)
  - /Project/src/middleware/auth.py (2 call sites)
  - /Project/tests/test_auth.py (1 call site)
  Warning: bidirectional dependency with /Project/src/middleware

Architecture

MCP Client Request
       |
[Tools Layer]     src/tools/        -- MCP tool definitions, input validation
       |
[Services Layer]  src/services/     -- Business logic (search, deps, security)
       |
[Core Layer]      src/core/         -- Model management, data conversion
       |
[SGraph Library]                    -- Graph operations (sgraph package)

See ARCHITECTURE.md for the detailed design.

Development

# Run tests
uv run python tests/run_all_tests.py
uv run python tests/run_all_tests.py unit          # Unit only
uv run python tests/run_all_tests.py integration   # Integration only

# Lint
uv run ruff check src/

# Run a single test file
uv run python -m pytest tests/unit/test_collect_deps.py -v

See CONTRIBUTING.md for how to contribute.

About

Built by Softagram using the open-source sgraph library. Licensed under MIT.