TypeMill Architecture

Quick navigation for understanding TypeMill's system design

TypeMill is a Pure Rust MCP server that bridges Language Server Protocol (LSP) functionality to AI coding assistants. The architecture is organized around a layered, service-oriented design.

Start Here

For Understanding the System

1. core-concepts.md - System architecture fundamentals

  • High-level crate structure and dependencies
  • 7-layer architectural model with enforcement
  • Code primitives framework (refactoring-focused)
  • Request lifecycle and data flow

2. specifications.md - API contracts and tool visibility

  • Public vs internal tools
  • Unified Refactoring API with dryRun pattern
  • Error codes and validation rules

For Implementing Features

3. lang_common_api.md - Language plugin development

  • LanguagePlugin trait implementation
  • Import handling, symbol extraction
  • Language-specific capabilities
  • Plugin registration and discovery

4. internal_tools.md - Internal tool reference

  • Backend-only tools (lifecycle, editing, workspace)
  • LSP plumbing (completions, signature help)
  • Legacy operations and migration paths

Architecture at a Glance

Layer Model (7 Layers)

Application    → Entry points (CLI, servers)
Handlers       → MCP tool implementations
Services       → Business logic, LSP integration
Language       → Language-specific plugins
Plugin API     → Plugin trait contracts
Foundation     → Core types, protocol, config
Support        → Testing, tooling

Rule: Each layer can only depend on layers below it (enforced by cargo-deny).

Tool Organization

Public MCP Tools (Magnificent Seven API):

  • Code Intelligence (2) - inspect_code, search_code
  • Refactoring (4) - rename_all, relocate, prune, refactor
  • Workspace (1) - workspace (with various actions)

Legacy/Internal Tools - Former public tools now internal, backend plumbing and LSP integration

See specifications.md#tools-visibility for complete lists.

Code Primitives Framework

TypeMill is built on refactoring primitives: atomic code transformations (rename_all, refactor actions, relocate, prune, etc.).

See core-concepts.md#code-primitives for details.

Request Flow

Transport (stdio/WebSocket)
  ↓
JSON parsing → McpMessage
  ↓
PluginDispatcher → Tool lookup
  ↓
Handler execution → Services (LSP, AST, etc.)
  ↓
Response → JSON → Transport

Key components:

  • mill-server - Transport, routing, state management
  • mill-handlers - MCP tool implementations
  • mill-services - LSP integration, AST caching, refactoring engine
  • mill-lsp - Language server client abstraction
  • mill-ast - Language plugin coordination

Key Design Principles

Safety First (dryRun Pattern)

All refactoring tools default to preview mode (dryRun: true). Execution requires explicit opt-in (dryRun: false).

Unified APIs

  • Refactoring tools share common structure: target → operation → dryRun → plan/apply
  • Analysis tools share common envelope: category → kind → scope → findings

Plugin Architecture

Language support is modular. Each language gets its own plugin (mill-lang-rust, mill-lang-typescript, etc.).

Layer Enforcement

Dependencies between crates are validated by cargo-deny to prevent circular dependencies and maintain clean architecture.

Where to Learn More

Understanding the system:

Implementing features:

Operational details: