An agentic toolchest for deconstructing, analyzing, and reconstructing software architectures.

---

Use It From Your AI Assistant (MCP)

Drydock ships as an MCP server — plug it into Claude Code, Cursor, VS Code, or any MCP-compatible assistant and use the analyzers as native tool calls.

pip install mcp

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "drydock": {
      "command": "python",
      "args": ["/path/to/Drydock/Tools/mcp_server.py"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "drydock": {
      "command": "python",
      "args": ["/path/to/Drydock/Tools/mcp_server.py"]
    }
  }
}

Then just ask your AI assistant: "Analyze the boundaries of this project" — it calls drydock_boundaries directly.

MCP Tool	What it answers
drydock_context	Everything — runs all analyzers in one shot
drydock_codemap	"What files, classes, and functions are in here?"
drydock_boundaries	"Where can I safely extract components?"
drydock_dependencies	"What does this project depend on?"
drydock_interfaces	"What does each module expose?"
drydock_structure	"How big and deep is this codebase?"
drydock_platforms	"What tech stack / runtimes are used?"

All tools also work standalone from the CLI — see Tools/README.md.

---

Or Use It From the CLI

# One-shot: understand an entire project
python Tools/analyzers/context_compiler.py /path/to/project --output context.json

# Just the boundary analysis (the killer feature)
python Tools/analyzers/boundary_detector.py /path/to/project --output boundaries.json

# Human-readable markdown
python Tools/analyzers/codemap.py /path/to/project --markdown

Example: Boundary Detection (JSON)

Run boundary_detector.py on a project and instantly know if components can be safely extracted:

{
  "summary": {
    "total_source_files": 8,
    "total_import_edges": 5,
    "clusters_found": 1,
    "bridge_files": 0,
    "orphan_files": 8
  },
  "extraction_suggestions": [
    {
      "cluster_id": 0,
      "name": "core",
      "files": 6,
      "extraction_risk": "low",
      "reason": "No external dependencies - clean extraction"
    }
  ]
}

Example: Code Map (Markdown)

Run codemap.py --markdown to get a human-readable index of everything in a codebase:

# Code Map: my-project

## Summary
Files: 8 | Languages: python (3,983 lines)

## Source Files
- boundary_detector.py (549 lines)
    fn extract_python_imports, extract_js_imports, build_import_graph,
    detect_clusters, find_bridge_files, detect_boundaries
- codemap.py (758 lines)
    fn classify_role, parse_python, parse_js_ts, parse_rust, parse_go,
    scan_file, find_entry_points, generate_codemap
- interface_extractor.py (646 lines)
    fn extract_python_interface, extract_js_ts_interface,
    extract_rust_interface, extract_go_interface

Language Support

Language	Code Map	Interfaces	Boundaries	Dependencies
Python	Full AST	Full AST	imports	AST + stdlib
JS/TS	Regex	Regex	imports	package.json
Rust	Regex	Regex	use/mod	Cargo.toml
Go	Regex	Regex	imports	go.mod
C#	Regex	Partial	—	—
Java	Regex	Partial	—	—

---

Philosophy

Like a naval drydock where ships are brought in for major overhauls, this workspace is designed for:

• Decompartmentalization — Breaking down large projects into understandable components
• Analysis — Mapping architectures, dependencies, and interfaces
• Extraction — Pulling out reusable pieces with clean boundaries
• Synthesis — Building new projects from extracted and original components
• Shipping — Releasing assembled projects back to the Ocean (production)

The Drydock Lifecycle

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│    OCEAN                    DRYDOCK                            OCEAN        │
│  (upstream)               (your yard)                       (downstream)    │
│                                                                             │
│  ┌─────────┐     ┌───────────────────────────────────┐     ┌─────────┐     │
│  │ GitHub  │     │                                   │     │  Your   │     │
│  │ GitLab  │ ──▶ │  INTAKE → WORK → RELEASE → SHIP  │ ──▶ │  Prod   │     │
│  │ etc.    │     │                                   │     │ Deploy  │     │
│  └─────────┘     └───────────────────────────────────┘     └─────────┘     │
│                                                                             │
│  Ships arrive    Ships get rebuilt with new parts      Ships return to sea │
│  for overhaul                                          as new vessels      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Structure

Drydock/
├── StartHere/          # Documentation, guides, templates
├── Ship_Yard/          # Incoming projects for decomposition
│   ├── _intake/        # Raw project clones (READ-ONLY)
│   ├── _analysis/      # Analysis documents
│   └── _extraction/    # Extracted components
├── Tools/              # Utilities for drydock operations
│   ├── intake/         # Project intake tools
│   ├── analyzers/      # Code analysis tools
│   ├── extractors/     # Component extraction tools
│   ├── scaffolders/    # Project scaffolding tools
│   ├── validators/     # Validation tools
│   ├── builders/       # Build and ship tools (Oryx, containerd)
│   └── shippers/       # Artifact shipping tools
├── Projects/           # New projects being assembled
├── Workbench/          # Experiments and prototypes
├── Release/            # Launch preparation dock
└── Ocean/              # Deployed fleet registry

Full Workflow (Intake → Ship)

# 1. Intake — bring a project in for analysis
python Tools/intake/git_intake.py https://github.com/microsoft/oryx --shallow --analyze

# 2. Analyze — understand the architecture
python Tools/analyzers/context_compiler.py Ship_Yard/_intake/oryx -o context.json

# 3. Find clean extraction points
python Tools/analyzers/boundary_detector.py Ship_Yard/_intake/oryx -o boundaries.json

# 4. Scaffold a new project from extracted parts
python Tools/scaffolders/project_scaffolder.py --name my-new-project

# 5. Build, release, ship
python Tools/builders/oryx_builder.py release Projects/my-new-project --version v1.0.0
python Tools/builders/oryx_builder.py ship Release/my-new-project --registry ghcr.io/myorg

Ship_Yard/_intake/           Ship_Yard/_analysis/         Ship_Yard/_extraction/
┌──────────────────┐        ┌──────────────────┐         ┌──────────────────┐
│ oryx/            │   ──▶  │ oryx/            │   ──▶   │ oryx/            │
│ semantic-kernel/ │        │   overview.md    │         │   detector/      │
│ my-project/      │        │   architecture.md│         │   interfaces/    │
└──────────────────┘        │   components/    │         └──────────────────┘
     (read-only)            └──────────────────┘              (parts)
                                                                  │
                                                                  ▼
Projects/                   Release/                      Ocean/
┌──────────────────┐        ┌──────────────────┐         ┌──────────────────┐
│ my-project/      │   ──▶  │ my-project/      │   ──▶   │ my-project/      │
│   src/           │        │   dist/          │         │   current/       │
│   tests/         │        │   Dockerfile     │         │   history/       │
│   docs/          │        │   manifest.toml  │         │     v1.0.0/      │
└──────────────────┘        └──────────────────┘         └──────────────────┘
   (assembled)                 (staged)                     (deployed)

All Tools

Tool	Purpose
MCP Server
mcp_server.py	Use all analyzers from Claude Code, Cursor, VS Code
Analyzers
context_compiler.py	One-shot full project understanding (runs all below)
codemap.py	Map files, classes, functions, entry points
boundary_detector.py	Find component clusters and extraction risks
interface_extractor.py	Extract public API surfaces
dependency_analyzer.py	Map imports and dependencies
structure_analyzer.py	Map project file structure
platform_detector.py	Detect runtimes (Node, Python, Rust, Go, .NET)
git_analyzer.py	Analyze git history for extraction insights
Intake / Build / Ship
git_intake.py	Bring projects into Drydock (clone + auto-analyze)
project_scaffolder.py	Create new project structure
oryx_builder.py	Build, release, ship, rollback (Docker)
containerd_builder.py	Build, release, ship, rollback (Docker-free)

Design Principles

• JSON-first — All tools default to JSON for AI consumption, --markdown for humans
• Pure stdlib — Zero external dependencies (except mcp for the MCP server)
• Non-destructive — Analyzers never modify source projects
• Composable — Each tool does one thing; context_compiler orchestrates all

---

"Ships in harbor are safe, but that's not what ships are built for."

License

Apache 2.0 — See LICENSE for details.