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 -e ".[mcp]"

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

{
  "mcpServers": {
    "drydock": {
      "command": "python",
      "args": ["-m", "drydock.mcp"]
    }
  }
}

Or use the legacy path:

{
  "mcpServers": {
    "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_extract	"Extract this component as a standalone package" (plan-only by default)
drydock_architecture	"What are the design principles and architectural properties?"
drydock_security	"Which modules handle secrets? Can ingress reach execution? What's the blast radius?"
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?"
drydock_git	"What files are hot? What's been extracted before?"
drydock_catalog_ingest	Ingest a repository into your component library
drydock_catalog_list	List repositories in your catalog
drydock_catalog_components	List extracted and detected components
drydock_catalog_facts	Get architectural facts from ingested repos
drydock_catalog_search	Full-text search across your catalog

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

---

Or Use It From the CLI

# One-shot: understand an entire project
python3 -m drydock.cli context /path/to/project --output context.json

# Just the boundary analysis (the killer feature)
python3 -m drydock.cli boundaries /path/to/project --output boundaries.json

# Architectural analysis (design principles, cycles, layering)
python3 -m drydock.cli architecture /path/to/project --markdown

# Plan an extraction (no writes; see what will happen)
python3 -m drydock.cli extract /path/to/project --dir component_path --markdown

# Execute the extraction (materialize the package)
python3 -m drydock.cli extract /path/to/project --dir component_path -o /output

# Human-readable markdown
python3 -m drydock.cli codemap /path/to/project --markdown

# Build a persistent library of ingested projects
python3 -m drydock.cli catalog ingest /path/to/project --store
python3 -m drydock.cli catalog search "Parser"
python3 -m drydock.cli catalog diagram repo_id --kind layers --markdown

# See all tools
python3 -m drydock.cli list

Example: Boundary Detection (JSON)

Run drydock boundaries on a project and instantly know if components can be safely extracted:

{
  "summary": {
    "total_files": 8,
    "files_in_graph": 8,
    "resolved_edges": 5,
    "unresolved_imports": 0,
    "external_imports": 0,
    "ambiguous_imports": 0,
    "clusters_found": 1,
    "bridge_files": 0,
    "orphan_files": 0
  },
  "clusters": [
    {
      "id": 0,
      "file_count": 6,
      "files": ["src/core.py", "src/api.py", "src/db.py", "src/models.py", "src/auth.py", "src/utils.py"],
      "common_prefix": "src",
      "internal_edges": 12,
      "cohesion": 0.95,
      "external_dep_count": 0,
      "external_deps": [],
      "extraction_risk": "low",
      "extraction_reason": "No external dependencies or dependents"
    }
  ],
  "bridges": {"total": 0, "top": []},
  "orphans": [],
  "meta": {"project": "my-project", "root": "/path/to/project", "files_walked": 8, "truncated": false, "include_tests": true, "elapsed_ms": 42}
}

Example: Code Map (Markdown)

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

# Code Map: my-project

`/path/to/project`

8 files walked · 1/1 sections ok

## Summary

| Metric | Value |
|--------|-------|
| Files | 5 |
| Languages | python (1,250 lines) |

## Entry Points

- `src/main.py` (detected from filename)

## Source Files

- `src/core.py` (240 lines, python)
  - `class CoreEngine`
    - `def __init__(self, config: Dict) -> None`
    - `def process(self, data: Any) -> Any`
  - `class Logger`

Language Support

All analyzers work across all supported languages. Language backends use AST analysis for Python and regex for others.

Language	Extensions	Fidelity	Analysis Scope
Python	.py, .pyi	AST	Full symbol extraction, import resolution, interfaces
JavaScript	.js, .jsx, .mjs, .cjs	Regex	Imports, exports, declarations
TypeScript	.ts, .tsx, .mts, .cts	Regex	Imports, exports, type declarations
Go	.go	Regex	Imports, packages, public identifiers
Rust	.rs	Regex	Use/mod declarations, public APIs
C#	.cs	Regex	Using/namespace, public members
Java	.java	Regex	Import/package, public classes/interfaces

Note: AST backends see nested/conditional declarations and macro expansions. Regex backends cannot see these but work without additional dependencies. All languages detect component boundaries via import graphs.

---

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

Quick Workflow (Intake → Analyze → Extract)

# 1. Analyze — understand the architecture
python3 -m drydock.cli context /path/to/project -o context.json

# 2. Find clean extraction points (plugin seams: contracts + implementers)
python3 -m drydock.cli extract /path/to/project --list-seams --markdown

# 3. Find cluster-based boundaries (tight module groups)
python3 -m drydock.cli boundaries /path/to/project -o boundaries.json

# 4. Inspect interfaces and dependencies
python3 -m drydock.cli interfaces /path/to/project --markdown
python3 -m drydock.cli dependencies /path/to/project

# 5. Git history — which files are stable?
python3 -m drydock.cli git /path/to/project --days 90

# 6. Extract a seam or cluster as a standalone package
python3 -m drydock.cli extract /path/to/project --seam path/to/contract.py -o /output

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
Extraction
extract	Materialize components as standalone packages with dependencies resolved
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.