Time Complexity MCP

An MCP server that estimates Big-O time complexity of your code through static analysis. It parses source files into ASTs using tree-sitter, detects loops, recursion, and known stdlib calls, then reports per-function complexity with line-level annotations.

Built for AI coding assistants — works with Claude Code and GitHub Copilot.

Supported Languages

Language	Extensions	Grammar
JavaScript	.js, .mjs, .cjs, .jsx	tree-sitter-javascript
TypeScript	.ts, .tsx	tree-sitter-typescript
Dart	.dart	vendor NAPI binding
Kotlin	.kt, .kts	tree-sitter-kotlin
Java	.java	tree-sitter-java
Python	.py	tree-sitter-python
PHP	.php	tree-sitter-php
Go	.go	tree-sitter-go

What It Detects

• Loop nesting — for, while, do-while with depth tracking. Constant-bound loops (e.g., for i in range(10)) are recognized as O(1).
• Recursion — linear recursion (O(n)) vs branching recursion like fibonacci (O(2^n)).
• Known stdlib methods — .sort() as O(n log n), .filter()/.map() as O(n), .push()/.pop() as O(1), etc. Each language has its own patterns.
• Combined complexity — an O(n) method inside an O(n) loop correctly reports O(n^2).

Tools

The server exposes 5 MCP tools:

Tool	Description
analyze_file	Analyze all functions in a source file. Returns per-function Big-O with reasoning and line annotations.
analyze_function	Analyze a single function by name or line number.
analyze_directory	Scan a directory for all supported files. Returns a summary with hotspots (top 5 most complex functions).
analyze_github_repo	Clone a GitHub repo and analyze complexity. Accepts owner/repo or full URL. Requires git in PATH.
get_supported_languages	List supported languages with file extensions.

Setup

Install from Release (recommended)

Download the prebuilt bundle for your platform from the latest release:

Platform	File
macOS (Apple Silicon)	time-complexity-mcp-darwin-arm64-v*.tar.gz
Linux x64	time-complexity-mcp-linux-x64-v*.tar.gz
Linux arm64	time-complexity-mcp-linux-arm64-v*.tar.gz
Windows x64	time-complexity-mcp-win32-x64-v*.zip

Extract and configure:

# macOS / Linux
tar xzf time-complexity-mcp-darwin-arm64-v*.tar.gz

# Windows
Expand-Archive time-complexity-mcp-win32-x64-v*.zip

No C++ compiler or npm install required — just Node.js 18+. The analyze_github_repo tool also requires git in PATH.

Install from Source

Requires Node.js 18+ and a C++ compiler (Xcode CLI tools on macOS, build-essential on Linux).

git clone https://github.com/Luzgan/time-complexity-mcp.git
cd time-complexity-mcp
npm install
npm run build

The postinstall script automatically builds the vendor Dart grammar.

Configure with Claude Code

Add to your project's .mcp.json (or ~/.claude.json for global access):

{
  "mcpServers": {
    "time-complexity": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/time-complexity-mcp/dist/index.js"]
    }
  }
}

Then restart Claude Code. The tools analyze_file, analyze_function, analyze_directory, analyze_github_repo, and get_supported_languages will be available automatically.

Configure with GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "time-complexity": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

If the MCP lives outside your workspace, replace ${workspaceFolder}/dist/index.js with the absolute path.

Usage Examples

Once configured, your AI assistant can call the tools directly.

Analyze a file

> Analyze the complexity of src/utils/sort.ts

Returns each function with its Big-O, reasoning, and line-level annotations:

bubbleSort (lines 1-10): O(n^2)
  Found 2 variable-bound loop(s), max nesting depth: 2. Overall: O(n^2).

  Line annotations:
    Line 2: O(n) — for_statement loop (nesting depth: 1)
    Line 3: O(n^2) — for_statement loop (nesting depth: 2)

Analyze a single function

> What's the complexity of the fibonacci function in recursion.py?

Analyze a GitHub repository

> Analyze the complexity of facebook/react

or with a full URL:

> Analyze https://github.com/expressjs/express, focus on the lib/ directory

Clones the repo temporarily, analyzes it, and returns results with repo-relative file paths. Requires git installed.

Scan an entire codebase

> Scan src/ for complexity hotspots

Returns a summary with the top 5 most complex functions across all files:

Files analyzed: 27
Total functions: 150

Breakdown:
  O(1):       102
  O(n):        40
  O(n log n):   1
  O(n^2):       4
  O(n^3):       2
  O(2^n):       1

Hotspots:
  1. src/analyzer/base-analyzer.ts → walk: O(2^n)
  2. src/tools/analyze-directory.ts → analyzeDirectory: O(n^3)
  ...

Architecture

src/
  index.ts                  # Entry point — stdio MCP transport
  server.ts                 # MCP tool registration
  analyzer/
    base-analyzer.ts        # Abstract base class (template method pattern)
    types.ts                # Core types (BigOComplexity, FunctionNode, etc.)
    complexity.ts           # Complexity arithmetic (max, multiply, fromDepth)
  languages/
    index.ts                # Language registry
    javascript/             # JS/TS analyzer
    dart/                   # Dart analyzer
    kotlin/                 # Kotlin analyzer
    java/                   # Java analyzer
    python/                 # Python analyzer
    php/                    # PHP analyzer
    go/                     # Go analyzer
  tools/                    # MCP tool implementations
  utils/                    # File I/O & formatting
vendor/
  tree-sitter-dart/         # Custom NAPI binding for Dart grammar
tests/
  *.test.ts                 # Per-language test suites (99 tests total)
  fixtures/                 # Sample source files

Each language analyzer implements 9 template methods from BaseAnalyzer:

getGrammar()              → tree-sitter grammar object
getFunctionNodeTypes()    → AST node types for functions
getLoopNodeTypes()        → AST node types for loops
getCallNodeTypes()        → AST node types for calls (e.g., "call_expression", "method_invocation", "call")
getKnownMethods()         → stdlib method complexity patterns
extractFunctionName()     → function name from AST node
extractParameters()       → parameter names from AST node
isConstantLoop()          → detect constant-bound loops
getCallName()             → function/method name from call node

Development

npm run build       # Compile TypeScript (also type-checks)
npm test            # Run all 99 tests
npm run test:watch  # Watch mode
npm run dev         # Run server via tsx (no build needed)

Security

• Static analysis only. Code is parsed into ASTs and inspected — never evaluated, executed, or imported.
• Read-only file access. Source files are read for parsing. Nothing is written, modified, or deleted.
• Network access (opt-in). The analyze_github_repo tool invokes git clone to fetch public GitHub repos. All other tools run locally with no network access. Clone URLs are restricted to HTTPS GitHub URLs only.
• Trusted native addons. Tree-sitter grammars are compiled NAPI addons from verified sources.

License

MIT