Saturn Semantic Code Knowledge Graph + MCP Server

A local first code intelligence server that turns your repository into a queryable knowledge graph for AI coding agents (Claude, Cursor, Aider, etc.)

Table of Contents

1. What is Saturn?
2. Features
3. Quick Start
4. How to Run
5. Available Tools
6. Project Structure
7. Architecture Highlights
8. Connecting to AI Agents
9. Troubleshooting
10. Roadmap

What is Saturn?

Saturn is a local first semantic code graph server built for AI coding agents. It parses your codebase using Tree sitter, builds a rich knowledge graph in SQLite, and exposes structured tools via the Model Context Protocol (MCP).

It works with:

• Terminal agents (Claude Code, Cursor, Aider, etc.) via stdio
• claude.ai via SSE + Cloudflare Tunnel

Features

• Multi-language AST parsing (Go, Python, JavaScript/TypeScript, Rust)
• Semantic knowledge graph with functions, classes, calls, routes, and more
• 14 tools for agents (trace_callers, run_impact_analysis, validate_patch, etc.)
• Incremental file watching (only re indexes changed files)
• Docker sandbox for safe code execution (validate_patch)
• Cloudflare tunnel integration for claude.ai
• Cost and usage tracing
• Fast and lightweight (Node.js + SQLite)

Quick Start

1. Clone & Install

git clone https://github.com/arijiiiitttt/saturn
cd saturn
bun install

2. Run Saturn

bun start
# or
node src/index.js

By default, Saturn indexes your current directory (.).

How to Run

Basic Usage

node src/index.js --repo /path/to/your/project

Flags

Flag	Description	Default
--repo	Path to repository	.
--db	Database file	.saturn.db
--port	SSE server port	3333
--workers	Number of AST parser workers	8
--no-tunnel	Disable Cloudflare tunnel	false
--no-stdio	Disable stdio transport	false

Example

node src/index.js --repo ~/Projects/my-awesome-app --port 4444

Available Tools (MCP)

Saturn exposes these tools to AI agents:

• get_architecture — Full repo overview
• find_symbol — Search any symbol
• trace_callers / trace_callees — Call graph traversal
• run_impact_analysis — See what a change would break
• find_dead_code — Unused code detection
• get_http_routes — All API routes across frameworks
• validate_patch — Run code safely in a Docker sandbox
• refresh_index, get_file_symbols, detect_clusters, and more

Project Structure

saturn/
├── src/
│   ├── index.js          # Entry point
│   ├── ast/               # Tree-sitter parsing + extractors
│   ├── db/                # SQLite schema + queries
│   ├── mcp/               # MCP server + tool handlers
│   ├── sandbox/            # Docker code execution
│   ├── watcher/            # File change detection
│   ├── tunnel/             # Cloudflare tunnel
│   └── tracer/             # Usage & cost tracking
├── .saturn.db             # Knowledge graph database
└── package.json

Architecture Highlights

• Tree-sitter for accurate multi-language parsing
• Worker threads for fast parallel indexing
• SQLite + WAL for reliable storage
• Incremental updates via file watcher
• Isolated Docker sandbox for testing patches
• Dual transport (stdio + SSE)

Connecting to AI Agents

Terminal Agents (Claude Code, Cursor, Aider)

Just run Saturn — it connects automatically via stdio.

claude.ai (Browser)

1. Run Saturn (the tunnel starts automatically)
2. Open claude.ai
3. Go to Settings → Integrations
4. Add a custom integration using the URL shown in your terminal

Troubleshooting

Issue	Solution
cloudflared not installed	Install via brew or the official instructions
Docker sandbox not working	Start Docker Desktop
Indexing too slow	Increase --workers
Port already in use	Use --port 4444
Database corrupted	Delete .saturn.db and restart

Roadmap

• More language support (Java, C#, PHP, etc.)
• Better cluster detection
• Graph visualization UI
• Remote MCP support
• Advanced query language

Contributions, stars, and feedback are welcome!