Lexomni MCP

Lexomni MCP

MCP (Model Context Protocol) server for local knowledge management with Markdown and PDF indexing using SQLite FTS5.

Author: PagansDev (Paulo Gabriel Neves Santos) | Repository: github.com/PagansDev/lexomni-mcp

---

English

Usage

As a local MCP server

Lexomni MCP automatically discovers the _lexomni workspace in your project by walking up the directory tree from cwd. If not found, it creates the structure automatically.

1. Configure your MCP client (e.g., Cursor):

"lexomni": {
      "command": "npx",
      "args": ["-y", "lexomni-mcp"],
      "cwd": "/path/to/your/project", # (optional) only if needed
      "env": {}
    },

Note: Usually you don't need to define cwd; the MCP client typically uses the current workspace directory. Add "cwd": "/path/to/your/project" if needed.

Note: npx downloads and execute the package automatically, you don't need to install anything, but in those earlier releases is recomended to clone the repository and run in locally until I adress the issues.

In that case, after you clone the repository, the configuration would be:

wsl:

"lexomni-local": {
      "command": "wsl.exe",
      "args": [
        "-d", "distro-your.version", # e.g. : Ubuntu-24.04 
        "--",
        "bash", "-lc",
        "npx -y /path/to/cloned/repository"
      ]
    }

Windows:

"lexomni-local": {
  "command": "cmd.exe",
  "args": [
    "/c",
    "npx",
    "-y",
    "C:\\Users\\User\\Your\\Folders\\lexomni-mcp"
  ]
}

1. Add your documents:

• _lexomni/user/ - User markdown (guidelines, architecture, etc.)
• _lexomni/agent/ - Agent notes (auto-generated)
• _lexomni/books/ - PDFs (books, documentation, etc.)

The folder structure (_lexomni/user, _lexomni/agent, _lexomni/books, _lexomni/index) is created automatically on first run.

Available Tools

Agent handles parameters on its own

lexomni_listSources

Lists all documents (MD and PDF) in the workspace.

Parameters: none

Example: ``json { "workspace": "/path/to/project/_lexomni", "count": 5, "docs": [...] } ``

lexomni_buildIndex

Indexes documents into SQLite FTS5 for fast search.

Parameters:

• sources (optional): array of ["user", "agent", "books"]

lexomni_searchDocs

Keyword search across indexed documents.

Parameters:

• query (required): string, min 2 characters
• sources (optional): filter by source
• limit (optional): max results (1-50, default 10)

Example: ``json { "query": "clean architecture", "hits": [ { "docId": "user:user/guidelines.md", "chunkIndex": 0, "snippet": "...about [clean] [architecture]...", "source": "user", "relPath": "user/guidelines.md" } ] } ``

lexomni_readDoc

• docId (required)
• Type: string

Purpose: unique identifier of the document in the index. > Constraint: at least 3 characters. Typical source: taken from a hit returned by lexomni_searchDocs.

• chunkIndex (optional)

Type: integer Minimum: 0 Purpose: which chunk (piece) of the document to read. If omitted: usually defaults to the first chunk (0), depending on implementation.

• maxChars (optional)

Type: integer Range: 200–20000 Purpose: maximum number of characters of text to return for that chunk, useful to limit response size.

lexomni_writeNote

• filename (required)

Type: string Purpose: name of the markdown file to create or update in the agent’s notes area. > Constraint: at least 1 character.

• content (required)

Type: string Purpose: markdown content to write into the file. > Constraint: at least 1 character.

• mode (optional)

Type: string Allowed values: "overwrite" – replaces the existing file content entirely. "append" – appends content to the end of the existing file. Default: "overwrite" if not specified.

Security

• Path traversal blocked (no ../ allowed)
• Access restricted to workspace _lexomni
• Write access limited to _lexomni/agent/

Architecture

_lexomni/               # In user's project
  user/                 # Guidelines, architecture (read-only)
  agent/                # Agent notes (writable)
  books/                # PDFs (read-only)
  index/                # SQLite FTS5 (generated)
    lexomni.sqlite

Multilingual Strategy

Lexomni does not translate text internally. To find docs in PT and EN for e.g. :

1. Agent expands queries before searching:

• "arquitetura em camadas" → also searches "layered architecture"
• "fila" → also searches "message queue", "job queue"

1. Living glossary at _lexomni/agent/glossary.md:

• Agent learns new terms via web search
• Improves search quality over time

Development

npm run build    # Build production
npm run dev      # Watch mode
npm start        # Run built server

---

License

MIT © Paulo Gabriel Neves Santos