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.
- 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: File access is restricted to the indexed directory to prevent unauthorized access.
- 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.
You need to have Rust installed.
cargo install terrainAdd the following to your Cargo.toml:
[dependencies]
terrain = { version = "0.1.0", default-features = false }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.resolve_dir/collect_markdown_files/build_engine— Utility functions for directory resolution, Markdown file collection, and search engine initialization.
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").
-
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.
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.tomlSee terrain.config.example.toml for all available options.
The server provides the following tools:
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 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.
Licensed under either of
at your option.