Terrain
A lightweight, configurable full-text search MCP server for Markdown knowledge bases.
Ask AI about Terrain
Powered by Claude Β· Grounded in docs
I know everything about Terrain. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
terrain
terrain is a lightweight, configurable, local-first full-text search engine for your Markdown knowledge base, with built-in support for Japanese text.
It runs as a command-line MCP (Model Context Protocol) server, indexing a specified directory of .md files and exposing search and retrieval tools.
Features
- Full-Text Search: Powered by the
traverzesearch engine, built ontantivy. - Japanese Support: Utilizes
linderawith an IPADIC dictionary for accurate morphological analysis and tokenization of Japanese text. - MCP Server: Exposes a simple, machine-readable tool interface over standard I/O.
- Secure:
read_fileonly serves paths that have been registered in the index, so registration is the permission grant. - Configurable: Customize tool descriptions via a TOML configuration file to tailor AI model behavior.
- Cross-Platform: Built with Rust, runs on Windows, macOS, and Linux.
Installation
You need to have Rust installed.
As a CLI tool
cargo install terrain
As a library
Add the following to your Cargo.toml:
[dependencies]
terrain = { version = "0.1.0", default-features = false }
Disabling default features drops the clap and notify dependencies that the CLI uses, leaving a lean library suitable for embedding.
The library exposes the following public API:
Configβ Load and parse a TOML configuration file.TerrainServerβ The MCP server handler, ready to be plugged into anrmcptransport. Constructed withTerrainServer::new(engine, indexed_paths, &config).IndexedPathsβ A cloneable, shared set of paths currently registered in the index.read_fileconsults this set to authorize reads, so the embedding app controls access by registering paths.resolve_dir/build_engineβ Utility functions for directory resolution and search engine initialization.
The library does not scan directories or watch the filesystem on its own β embedding apps decide which files to register and when to re-index. See src/main.rs for a reference integration that walks a directory of .md files and keeps the index in sync via notify.
MCP Client Setup
To use terrain with an MCP-compatible client such as Claude Desktop, add the following to your client's configuration file (e.g., claude_desktop_config.json):
{
"mcpServers": {
"terrain": {
"command": "terrain",
"args": ["--dir", "/path/to/your/notes"]
}
}
}
If you built from source without cargo install, use the full path to the executable instead (e.g., "/path/to/terrain").
Usage
-
Start the server: Run the program from your terminal, pointing it to the directory containing your Markdown files.
terrain --dir /path/to/your/notes -
Indexing: The server will first index all Markdown files in the specified directory. You will see a message indicating how many files have been indexed.
indexed 1234 markdown files from /path/to/your/notes -
Interact via MCP: Once indexed, the server listens on
stdinfor MCP JSON requests and sends responses tostdout. You can use this interface with any MCP-compatible client or controller.
Configuration
In MCP, tool descriptions directly influence how the AI model decides when and how to use each tool. You can customize these descriptions to better suit your use case by providing a TOML configuration file.
terrain --dir /path/to/your/notes --config terrain.config.toml
See terrain.config.example.toml for all available options.
MCP Tools
The server provides the following tools:
search
Search indexed Markdown files and return matching file paths, scores, and snippets.
- Description: This tool is highly optimized for Japanese text. Use it to find relevant context to answer a user's question. It returns a list of matching absolute file paths, relevance scores, and surrounding text snippets.
- Parameters:
query(string, required): The search query. You can specify multiple keywords separated by spaces.limit(integer, optional): The maximum number of search results to return (default: 20).
- Example Return Value:
[ { "path": "/path/to/your/notes/example.md", "score": 18.72, "snippet": "This is a snippet of text surrounding the matched keyword." } ]
read_file
Read the full contents of a specific Markdown file.
- Description: Use this when you find a promising snippet from the
searchtool and need more detailed context. Provide the exact absolute file path retrieved from the search results. - Parameters:
path(string, required): The absolute path of the Markdown file to read. You must use the exact path returned by thesearchtool.
- Example Return Value: The full, raw content of the specified Markdown file.
License
Licensed under either of
at your option.
