Skip to main content

Queequeg

Queequeg logo

A static analysis MCP server for Python codebases. Queequeg gives AI assistants structured code context by tracing function and class dependencies across files — so instead of opening ten files to understand one function, the assistant calls one tool and gets everything it needs.

Why

When an AI assistant needs to understand a function, it typically reads the file, finds imports, reads those files, finds more imports, and so on. It loses context, misses things, and wastes tokens.

Queequeg does that traversal statically using AST analysis and returns a single structured result — the full dependency graph, assembled and ready to use.

Installation

pip install queequeg
# or
uv add queequeg

Setup with Claude Code

claude mcp add queequeg --scope user -- uvx --from queequeg queequeg-mcp

Then add a CLAUDE.md to your project (see CLAUDE.md example below) to tell Claude when and how to use it.

Tools

trace_code

Returns the full source of a symbol and all its transitive dependencies assembled into a single virtual file. Use this when you need to understand what a function actually does end-to-end.

Example — tracing uses_imported_function which calls shared_helper from another file:

# file: myproject/utils.py
def shared_helper():
    return "i am from another file"


# file: myproject/main.py
def uses_imported_function():
    return shared_helper()

No manual import chasing. Everything needed to understand the function is in one place.


trace_graph

Returns a JSON dependency graph of a symbol — what it calls and what those call, recursively. Use this for a structural overview without reading all the code.

Example:

{
  "myproject/main.py::uses_imported_function": {
    "type": "function",
    "file_path": "myproject/main.py",
    "dependencies": [
      "myproject/utils.py::shared_helper"
    ]
  },
  "myproject/utils.py::shared_helper": {
    "type": "function",
    "file_path": "myproject/utils.py",
    "dependencies": []
  }
}

trace_callers

Returns a JSON graph of every function that directly or transitively calls a given symbol. The target is the root — each node lists its callers. Use this for impact analysis before modifying a function.

Example — finding everything that calls process_user:

{
  "myproject/users.py::process_user": {
    "type": "function",
    "file_path": "myproject/users.py",
    "callers": [
      "myproject/api.py::create_user"
    ]
  },
  "myproject/api.py::create_user": {
    "type": "function",
    "file_path": "myproject/api.py",
    "callers": [
      "myproject/handlers.py::handle_request"
    ]
  },
  "myproject/handlers.py::handle_request": {
    "type": "function",
    "file_path": "myproject/handlers.py",
    "callers": []
  }
}

trace_callers accepts an optional search_path parameter. It defaults to the directory of the target file — pass the project root to scan the whole codebase.


Limitations

  • Only resolves static dependencies — dynamic dispatch, getattr(obj, name)(), callbacks stored in dicts or lists, and __call__ are not traced
  • Does not cross package boundaries — third-party library internals are not traced
  • String annotations (e.g. def foo(x: "MyModel")) are not resolved
  • importlib.import_module() with a dynamic string argument cannot be traced

CLAUDE.md example

Add this to your project's CLAUDE.md to instruct Claude when to use queequeg:

# Tools

## Queequeg MCP Tools

Use queequeg for understanding code structure, but only in specific cases:
- `mcp__queequeg__trace_code` — get the full code of a symbol and all its dependencies
- `mcp__queequeg__trace_graph` — get a structural overview of a symbol's dependency graph
- `mcp__queequeg__trace_callers` — find all functions that call a given symbol (impact analysis)

### When queequeg is useful:
- Function has dependencies scattered across **multiple different files**
- You want to pull a small relevant portion of a large file without guessing offset/limit ranges
- Understanding a deep dependency chain (e.g., function A calls B calls C calls D across different modules)
- Before modifying a function — use trace_callers to find everything that will be affected

### When queequeg is NOT useful:
- All related functions are in the **same file and nearby** (just read the file)
- Small files where reading the whole thing is faster than using a tool
- You need file context, comments, or surrounding code for understanding

### Limitations (apply to all queequeg tools):
- Only resolves **static** dependencies — dynamic dispatch, `getattr(obj, name)()`, callbacks stored in dicts or lists, and `__call__` usage will be missed
- Does not cross package boundaries — third-party library internals are not traced
- String annotations (e.g. `def foo(x: "MyModel")`) are not resolved
- `importlib.import_module()` with a dynamic string argument cannot be traced

### Special case:
If anything requires tree-sitter analysis, use queequeg — it has tree-sitter built in and can be extended for custom analysis needs.

Metadata

Release files for queequeg 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for queequeg 0.1.1
File Size Uploaded Provenance Actions
queequeg-0.1.1.tar.gz 39.0 kB Without provenance Details for queequeg-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for queequeg 0.1.1
File Interpreter ABI Platform Actions
queequeg-0.1.1-py3-none-any.whl Python 3 none any Details for queequeg-0.1.1-py3-none-any.whl

Total release size: 62.9 kB

Release files / queequeg-0.1.1.tar.gz

Download URL queequeg-0.1.1.tar.gz
Size 39.0 kB
Tags Source
SHA-256 checksum
How to use checksums
785912f0a2b823331360241db2f8d7ee0fb4e02cb9a1623aa557c9ad4365761d
BLAKE2b-256 checksum
How to use checksums
0791619b0e51d2f597cf80a5cc06a47cfef6be614cbdacf698de4719c70db886
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / queequeg-0.1.1-py3-none-any.whl

Download URL queequeg-0.1.1-py3-none-any.whl
Size 23.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
34468975be8c44627cc63e5f5489ef3f907c40a872ecffdc69ca919bec140991
BLAKE2b-256 checksum
How to use checksums
a84b12ba29f31e4837b79e5464de8a1e277e8cfe1869dfba3bbf933298f76338
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for queequeg 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page