# AsterMind MCP server

> Reranks and filters retrieved context locally to reduce RAG token usage before sending data to an LLM.

- Repository: https://github.com/AsterMindAI/astermind-mcp
- Page: https://hostedmcp.org/servers/astermindai/astermind-mcp
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.1.0

## Install

### Claude Code

```sh
claude mcp add astermind-mcp -- npx -y @astermind/astermind-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "astermind-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astermind/astermind-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "astermind-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@astermind/astermind-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"astermind-mcp","type":"stdio","command":"npx","args":["-y","@astermind/astermind-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "astermind-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astermind/astermind-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add astermind-mcp -- npx -y @astermind/astermind-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.astermind-mcp]
command = "npx"
args = ["-y", "@astermind/astermind-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user astermind-mcp npx -- -y @astermind/astermind-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "astermind-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astermind/astermind-mcp"
      ]
    }
  }
}
```

## Tools (10)

- `rerank_documents`: Rank candidate documents/chunks by relevance to a query using an on-device ELM reranker. Best when the query shares vocabulary with the documents (typical RAG). Lexical (TF-IDF) based: strong on keyword overlap, weaker on pure-synonym matches.
- `filter_context`: Drop documents not relevant to the query so you feed the LLM a small, relevant context instead of everything. Reports exact tokens saved using an OpenAI-compatible tokenizer. This is the core token-reduction tool.
- `compress_context`: One-shot token saver: filter candidate documents to what is relevant and return a compact, numbered context block ready to paste into a prompt, plus token-before/after accounting.
- `classify_text`: Classify text into your categories using an on-device ELM trained on the labeled examples you provide. Requires at least one example per category. Returns a confidence and honestly flags low-confidence results. Use this to route/label locally instead of paying an LLM to classify.
- `detect_language`: Coarse language detection over 6 European languages (English, Spanish, French, German, Italian, Portuguese) using an on-device classifier. Runs locally with no API call.
- `semantic_search`: Return the top documents matching a query from a provided set, scored by an on-device lexical (TF-IDF) reranker. Strong on keyword overlap; not a transformer embedding search.
- `generate_embeddings`: Produce deterministic local char-level embeddings for a list of texts. Good for clustering, dedupe, and near-duplicate detection. Not a substitute for large transformer embeddings on nuanced semantics.
- `compare_texts`: Cosine similarity (0..1) between two texts using local embeddings. Best for detecting near-duplicates / paraphrase overlap, not fine-grained semantic ranking.
- `count_tokens`: Count tokens in a string or array of strings using an OpenAI-compatible BPE tokenizer (o200k/cl100k family). Useful for measuring context size and budgeting.
- `estimate_savings`: Given the full context vs the filtered context you plan to send an LLM, compute tokens removed, percent saved, and (optionally) dollars saved per call for a given model input price.

## FAQ

### Does this require an API key or internet connection?

No, it runs locally on your machine with no network calls or API keys required.

### How much can I save on context tokens?

On average, you can save approximately 66.9% of context tokens by filtering retrieved candidates.

### What are the hardware requirements for running AsterMind?

It runs on Node 18+ and does not require a GPU.

### How does the reranker work?

The reranker uses lexical (TF-IDF) matching, which excels when the query and answer share vocabulary.
