Getting Started
Getting Started
This guide covers prerequisites, building the project, running the quality gate, and operating the
tower MCP server for the first time.
Prerequisites
Rust toolchain
The toolchain is pinned in rust-toolchain.toml:
[toolchain]
channel = "1.100.0"
components = ["rustfmt", "clippy"]
profile = "minimal"rustup reads this file automatically on first use and installs the exact channel and components.
No extra build target is required: the engine and the native extensions all build for the host target.
(The previous WASM model needed wasm32-wasip1 and a WASI SDK; neither is required any more.)
If you do not have rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shcargo-deny
Used to enforce license and advisory policy (deny.toml at the workspace root).
cargo install cargo-deny --lockedClone and build
git clone <repository-url> tower
cd tower
# Build the host binary (tower) and every native extension.
cargo build # or: make buildThe host binary produced is target/debug/tower; the reference extension binaries
(ast_extension, debug_extension, hello_extension, lsp_extension, lint_extension) are also under
target/debug/.
Quality gate
Run these four checks in order before every merge. The CI pipeline (ci.yml) executes them in exactly
this sequence; a step must pass before the next runs. make gate runs the whole sequence.
1. Format check
cargo fmt --all --check # make fmt-check2. Clippy (warnings are errors)
cargo clippy --workspace --all-targets -- -D warnings # make clippy3. Run the test suite
Build native extension binaries before running tests so the host integration
tests can locate sidecars under target/debug/. There is no WASM build step and
no WASI SDK.
cargo build --workspace --bins
cargo test --workspace # make test4. License and advisory policy
cargo deny check # make denyRunning the engine as an MCP server
tower is a JSON-RPC 2.0 server that speaks over stdin/stdout using newline-delimited JSON (no
Content-Length header). Start it with:
cargo run -p core_engineOr, after a release build:
cargo build --release -p core_engine
./target/release/towerWorkspace root resolution
The engine needs to know which directory to index. It resolves the workspace root in priority order:
| Priority | Mechanism | Example |
|---|---|---|
| 1 (highest) | --workspace-dir <path> CLI flag | tower --workspace-dir /home/user/myproject |
| 2 | TOWER_WORKSPACE environment variable | TOWER_WORKSPACE=/home/user/myproject tower |
| 3 (fallback) | Current working directory | cd /home/user/myproject && tower |
Sled database
On startup, tower creates .tower/db/ inside the workspace root and opens a sled embedded
database there. This directory is created automatically; no manual setup is required.
<workspace-root>/
└── .tower/
└── db/ ← sled database (persisted across restarts)Startup reconciliation
On every daemon startup, tower walks the eligible workspace inventory using the same
.towerignore, hidden-file, symlink, and regular-file rules as tower_reindex. It reconciles
that inventory with persisted state, adding missing files, removing confirmed stale or newly
excluded paths, and preserving identities for surviving paths. It reports the reconciliation
summary to stderr:
tower: reconciled index — 2 added, 1 removed, 310 unchangedThe repair is transactional and idempotent. A failed reconciliation prevents the daemon from serving a partial index; the next startup retries it. Unchanged files are not re-read, rehashed, or rewritten merely because the daemon restarted.
First session
The following is a minimal copy-paste session. Each line sent to stdin must be a single JSON
object terminated by a newline. Responses arrive on stdout the same way.
Start the server pointed at a project directory:
cd /path/to/your/project
cargo run -p core_engine
# stderr: tower: reconciled index — A added, R removed, U unchangedIn a second terminal (or pipe input to the process), send JSON-RPC messages.
Configure the workspace
tower init creates a canonical .tower/config.toml alongside .towerignore. The generated
configuration uses native sidecar settings under [extensions] and host-owned formatter commands
under [formatter.tools.<id>]; it does not create an index-completion marker or start external
tools. Existing files are preserved byte-for-byte.
See
Configuration for formatter fields, extension disabling, and
the required manual migration for obsolete [plugins] configuration.
Handshake
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} }Expected response:
{
"jsonrpc": "2.0",
"result": {
"capabilities": { "tools": {} },
"protocolVersion": "2024-11-05",
"serverInfo": { "name": "tower", "version": "0.1.0" }
},
"id": 1
}List available tools
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }The response lists the native tower_* tools plus any tools contributed by discovered extensions
(e.g. tower_ast_get_outline when the ast extension is present, or tower_lint_check
when the lint extension is present). Extension tools are always namespaced as
tower_<ext>_<tool_name>.
The native tower_rename_path tool is available without an extension. It moves
workspace-relative files or directories and accepts semantic_policy values
none, best_effort, and required; use dry_run:true to inspect the move
and any proposed reference edits before changing the workspace. See the
path rename how-to for a complete request
and the
MCP tool reference for the wire contract.
The native tower_safe_delete_symbol tool is listed even when extensions are unavailable. Planning
requires the AST extension and a configured semantic backend. It resolves a declaration, checks
references, and either returns a blocking report or applies a validated declaration and cleanup
plan. Use dry_run:true to inspect the report without changing files. See
Safe-delete a symbol.
Install extensions
From the Tower source checkout, install the reference extensions globally:
make install-extensions GLOBAL=1On Linux, this uses $XDG_DATA_HOME/tower/extensions when XDG_DATA_HOME is non-empty,
otherwise $HOME/.local/share/tower/extensions. Use an absolute XDG_DATA_HOME.
Without GLOBAL=1, installation stays local to the checkout’s .tower/extensions.
An explicit destination always wins, including with global mode:
make install-extensions GLOBAL=1 EXT_DEST="/path with spaces/extensions"The command builds the extensions and prints the destination before copying each manifest and
executable. EXTENSIONS=lint installs only lint; EXT_PROFILE=debug uses a debug build.
make install updates only the server, so run the extension installation command after updating it.
After replacing binaries, reload the shared daemon for each affected workspace and reconnect its
MCP clients. From that workspace, tower shutdown stops its daemon; reconnecting the clients
starts it again with the installed extensions. Installation itself does not stop running daemons.
Global extensions are available across projects. A workspace-local extension with the same name
in .tower/extensions/<name>/ takes precedence over its global copy. An explicit
--extensions-dir or TOWER_EXTENSIONS_DIR replaces both discovery scopes; install into that
location with EXT_DEST if you use this override.
No extensions in any scope simply serves the native tools; an extension that fails to spawn (or one
listed in the config disable list) is skipped with a stderr warning and never blocks startup. When the
same extension name appears in both scopes, the local copy wins. See
extensions.md
for the manifest schema, capabilities, activation, and the supervision/fault model.
Explore a type hierarchy
With an LSP binding configured for the file type, query the supertypes, subtypes, or both for a symbol position. Positions use zero-based lines and UTF-16 character offsets:
[lsp.rust]
command = "rust-analyzer"
args = []
extensions = ["rs"]{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "tower_lsp_type_hierarchy",
"arguments": {
"path": "src/lib.rs",
"line": 12,
"character": 7,
"direction": "both"
}
}
}The result separates supertypes and subtypes. If the language server is not configured or does
not support the capability, Tower returns supported:false with empty arrays so clients can fall
back to another navigation strategy. See
Type hierarchy for the
location and external-result contract.
Find a file
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": { "name": "tower_find_file", "arguments": { "query": "main.rs" } }
}List a directory
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "tower_list_dir",
"arguments": { "path": "src", "recursive": true, "max_depth": 1 }
}
}Search for text
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "tower_search_text",
"arguments": { "pattern": "fn main" }
}
}Read a file
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "tower_read_file",
"arguments": { "path": "src/main.rs" }
}
}Run standalone linters
Configure linters in <workspace>/.tower/config.toml under [lint.<language>]. The extension
matches files by extension and runs the configured command read-only.
[lint.rust]
command = "cargo"
args = ["clippy", "--message-format=json"]
extensions = ["rs"]
format = "rustc-json"
target = "none"
[lint.javascript]
command = "eslint"
args = ["--format", "json"]
timeout_secs = 10
extensions = ["js", "jsx", "ts", "tsx"]
format = "eslint-json"
target = "append"timeout_secs is optional. Omit it for no Tower-controlled duration limit, or set a positive integer
when a configured linter needs an explicit budget; the same deadline applies to lint checks and both
phases of a lint fix.
Call tower_lint_check with a path to lint one file, or with {} to lint every indexed file
that has a matching lint configuration.
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "tower_lint_check",
"arguments": { "path": "src/main.rs" }
}
}Call tower_lint_fix to apply structured fixes emitted by rustc-json or eslint-json linters.
The lint extension does not run linter in-place mutation modes; fixes are sent through Tower’s
CAS-guarded atomic write path. Use dry_run:true to return previews without changing files, and
unsafe:true only when you want to apply fixes marked unsafe or unknown by the linter.
{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "tower_lint_fix",
"arguments": { "path": "src/main.rs", "dry_run": true }
}
}Create a file
{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "tower_create_file",
"arguments": { "path": "notes.txt", "content": "hello world\n" }
}
}Mass find-and-replace
{
"jsonrpc": "2.0",
"id": 10,
"method": "tools/call",
"params": {
"name": "tower_global_replace",
"arguments": { "target": "old_name", "replacement": "new_name" }
}
}Response shape (success):
{
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "{\"files_changed\":3,\"replacements\":7,\"errors\":[]}"
}
]
},
"id": 10
}All tool responses follow the same envelope: result.content[0].text is a JSON string containing
the tool-specific payload.
Error codes reference
| Code | Meaning |
|---|---|
| -32700 | ParseError — malformed JSON or invalid UTF-8 |
| -32600 | InvalidRequest — wrong jsonrpc version |
| -32601 | MethodNotFound — unknown RPC method |
| -32602 | InvalidParams — missing required field in tool arguments |
| -32603 | InternalError — tool execution failed |
| -32001 | ToolNotFound — named tool not in the registry |
| -32002 | ResourceNotFound — domain entity not found |
Next steps
- architecture.md — hexagonal boundary, domain model, adapter wiring
- mcp-tools.md — the native tools and the extension tools in full detail
- extensions.md — authoring a native extension: protocol, capabilities, fault model
- development.md — contribution guide, TDD workflow, benchmark targets