Introduction

Midown is a powerful headless local context engine and CLI that maps your codebase dependencies for AI consumption and visually represents your architecture. By running locally, it allows tools like VS Code Copilot, Cursor, and Claude Desktop to intrinsically understand your repository layout without exhausting context tokens.

Installation

Install Midown globally using npm to ensure the CLI is available across all your projects.

$npminstall -g midown

Basic Workflow

To get Midown working with your codebase, follow this simple 4-step workflow:

Pin your project

Navigate to your project directory and run midown add .

Index your workspace

Run midown push to map the dependencies into a semantic graph.

Start MCP Server

Run midown start to spin up the background AI bridge.

Visualize Architecture

Run midown visualize to view the graph in a rich web UI.

MCP Server (AI Integration)

Midown includes a built-in Model Context Protocol (MCP) server. This standard allows AI assistants to selectively query your architecture documentation and code structure exactly when needed, preventing context-window bloat and saving processing tokens.

Connecting VS Code & Cursor

Update your MCP settings file (e.g. ~/.vscode/roocode/mcp-settings.json) to include Midown as a server:

{
  "mcpServers": {
    "midown": {
      "command": "midown",
      "args": ["start"]
    }
  }
}

Note: Ensure the Midown CLI is installed globally and is available in your system's PATH.

Available AI Tools

Once connected, the AI can invoke these tools:

get_codebase_graphReturns a highly-compressed, structural map of your entire codebase. Ideal for initial onboarding.
query_file_dependenciesSurgical lookup of what a specific file imports, and what other files depend on it.

Prompting Best Practices

AI models aggressively conserve tokens, meaning they may not instinctively use MCP tools unless instructed. Be explicit.

Example Prompt

"Use your MCP tools to call get_codebase_graphto understand the structure, then tell me exactly how the frontend authenticates with the backend based on the actual codebase structure."

Automating with Custom Instructions

Instead of prompting the AI every time, you can add a global rule so the agent automatically uses Midown to understand your codebase. Add this snippet to your AI's custom instructions (e.g., Cursor Rules, Roo Code / Cline Custom Instructions, or Claude's System Prompts):

When you need to understand the architecture, codebase structure, or file dependencies, you MUST ALWAYS use the Midown MCP tools first. 
1. Call `get_codebase_graph` to get a structural map of the project.
2. Call `query_file_dependencies` if you need surgical lookup of specific file imports and dependents.

CLI Commands Reference

midown add [directory]

Pins a folder structure to the engine memory map. Defaults to the current working directory.

midown push

Processes and indexes the directory node-edges natively via AST & Semantic Summaries. Required before starting.

midown start

Starts the background MCP server process, making the indexed graph available to AI tools on stdio.

midown visualize

Launches a local web-app visualization tool to let you explore the topological node network visually.

midown switch <directory>

Changes the active operational environment context to a different folder path.

midown set <key> / set-local <model>

Configures cloud API keys or sets the target local AI framework to be used during indexing.

FAQ & Edge Cases

Can the indexer handle indexing two repositories in 1 directory?

Yes! The indexer walks through the file system recursively. If you have multiple repositories (or a monorepo) within a single parent directory, you have two approaches:

Index as a single unified graph: Run midown add . at the parent directory level. Midown will scan everything inside, track cross-dependencies, and treat it as one large interconnected graph.
Index as isolated contexts: If you want to keep them strictly separate, navigate into each repository's subdirectory and run midown add . individually.

Can the indexer connect frontend API calls to backend endpoints?

Yes. While traditional AST parsers only detect explicit code imports (e.g., import x from './y'), Midown's engine also utilizes Semantic Summaries.

This means that even if your frontend and backend are decoupled across the network (e.g., making HTTP requests to a REST API), the AI can cross-reference the URL strings, route paths, and payload structures indexed in the graph. The context engine understands this semantic bridge flawlessly and can explain exactly which frontend component triggers which backend controller.

Midown Documentation