How do I use Lexomni MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lexomni MCP search my documents for 'clean architecture'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Lexomni MCP

by PagansDev

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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.

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"
  ]
}

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:

{
  "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:

{
  "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. :

Agent expands queries before searching:
- "arquitetura em camadas" → also searches "layered architecture"
- "fila" → also searches "message queue", "job queue"
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

Related MCP server: Hoard

License

MIT © Paulo Gabriel Neves Santos

Available Tools

5 tools

lexomni_buildIndexB

Generates/updates the SQLite FTS5 index from MDs and PDFs in _lexomni.

ParametersJSON Schema

Name	Required	Description	Default
`sources`	No

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals that the tool writes/updates an index but does not disclose whether existing indexes are replaced, whether the operation is expensive, whether file reading can fail, or whether special permissions are needed. This is a thin disclosure for a mutation-like tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no filler. The core action and resource are stated upfront, and the source location is included without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description leaves too much unsaid: the meaning of `sources`, the side effects of rerunning, and the recommended workflow alongside `lexomni_searchDocs` are all missing. It is barely more useful than the tool name alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the `sources` parameter at all. The enum values (`user`, `agent`, `books`) are somewhat self-explanatory, but an agent is left to guess whether they refer to directories, categories, or something else, and what omitting `sources` means.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Generates/updates') and resource ('SQLite FTS5 index'), with a clear input scope ('MDs and PDFs in _lexomni'). This clearly separates it from sibling tools like lexomni_searchDocs, lexomni_readDoc, and lexomni_writeNote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to build or refresh searchable indexes over documents, which suggests it should be run before searching. However, it never explicitly states when to run it, when not to run it, or how it relates to the sibling `lexomni_searchDocs` tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lexomni_listSourcesA

Lists available MDs (user/agent) and PDFs (books) in the _lexomni workspace.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral transparency burden. The verb 'Lists' implies a read-only operation, and the workspace scope is stated, but return format and any limitations are not disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and scope with no unnecessary detail. Every word contributes to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool, the description is sufficiently complete: it states what is listed, the categories, and the workspace. Without an output schema, the phrase 'Lists available...' reasonably implies the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the input schema is complete by default. The description does not need to explain parameter semantics, so the baseline score of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Lists' and identifies the resource types (MDs and PDFs) and scope (_lexomni workspace). This clearly distinguishes it from sibling tools like lexomni_searchDocs and lexomni_readDoc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a discovery/listing use case, but it does not explicitly state when to use this tool versus alternatives. Sibling names suggest different operations, yet the description provides no direct usage guidance or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lexomni_readDocB

Reads a chunk of an indexed document (by chunkIndex).

ParametersJSON Schema

Name	Required	Description	Default
`docId`	Yes
`maxChars`	No
`chunkIndex`	No

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that reading occurs, but does not explain chunk indexing semantics, behavior when chunkIndex is omitted or out of range, whether results are capped by maxChars, or what the response looks like. These are significant gaps for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with no filler or redundancy. 'Reads a chunk of an indexed document (by chunkIndex)' conveys the core operation efficiently and the key selection mechanism is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations, no output schema, and three parameters with zero schema descriptions, this one-liner is insufficient. It does not explain chunk semantics, the role of maxChars, required preconditions like an existing index, or the return structure. An agent would need to guess or inspect external documentation to invoke it correctly in non-trivial cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's lack of explanatory text. It only clarifies chunkIndex; docId and maxChars are left to inference from their names and schema constraints. The agent gets no explanation of how maxChars interacts with chunking or what docId refers to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the operation (reads) and the target (a chunk of an indexed document, selected by chunkIndex). This distinguishes it from sibling tools like lexomni_buildIndex, lexomni_searchDocs, and lexomni_writeNote, which have different verbs and resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool or what prerequisites exist, such as 'the document must first be indexed via lexomni_buildIndex'. There is no mention of alternatives or exclusions, leaving the agent to infer usage context from the word 'indexed'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lexomni_searchDocsB

Searches indexed documents by keyword (FTS).

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`sources`	No

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool searches indexed documents by keyword; it does not disclose the return format, result ordering, pagination/limit behavior, or that searchable content depends on a pre-built index. 'Indexed documents' hints at a prerequisite but is not sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It states the action (Searches), the object (indexed documents), and the method (keyword FTS) in an efficient, scannable way.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters, no annotations, and no output schema, the description is far too minimal. It leaves critical operational details undefined: what 'sources' does, how 'limit' behaves, and what the result looks like. An agent can call it with just 'query', but cannot reliably predict results or apply filters correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description only mentions 'keyword', which maps to the required query parameter. It says nothing about 'limit' (maximum results) or 'sources' (filtering by user/agent/books), leaving those parameters unexplained in both schema and description. The description does not compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Searches') and resource ('indexed documents') with a clear method ('by keyword (FTS)'). It is distinct from sibling tools like readDoc (direct retrieval), listSources (listing sources), buildIndex (building an index), and writeNote (writing), so an agent can tell search apart from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives, no exclusions, and no context about prerequisites (e.g., needing to build the index first). Sibling tools are known but never referenced, so the agent must infer when keyword search is the right choice from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lexomni_writeNoteB

Creates/updates a markdown file in _lexomni/agent (agent memory).

ParametersJSON Schema

Name	Required	Default
`mode`	No	overwrite
`content`	Yes
`filename`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is the only behavioral disclosure. It correctly identifies the tool as a mutation that creates or updates a markdown file in a scoped location, but it does not disclose that the default mode is overwrite, how append behaves, side effects, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. The verb, object, location, and purpose are stated in order, making the core meaning immediately visible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter write tool, the description plus schema is enough to make a plausible call. Yet with no annotations or output schema, it lacks a bit of surrounding context such as overwrite semantics and how this write relates to the other lexomni tools like buildIndex.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description adds no meaning for filename, content, or mode. The schema shows the parameter names and the mode enum, so the description does not compensate for the missing parameter-level guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (creates/updates), a concrete resource (markdown file), and a precise location (_lexomni/agent). This clearly distinguishes it from the read/search/list/index siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'agent memory' implies this is for persisting agent notes, and sibling names imply alternatives such as reading or searching. However, there is no explicit statement of when to choose this tool over alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv0.0.0-devAug 30, 2026
- First observedlexomni_buildIndex
- First observedlexomni_listSources
- First observedlexomni_readDoc
- First observedlexomni_searchDocs
- First observedlexomni_writeNote

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-08-30 13:20 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct function: listing sources, building the index, searching, reading a chunk, and writing a note. There is no overlap or confusion between tool purposes.

Naming Consistency5/5

All tools follow a consistent lexomni_verbNoun pattern (listSources, buildIndex, searchDocs, readDoc, writeNote). The naming is uniform and predictable.

Tool Count5/5

Five tools is well-scoped for a document indexing and retrieval server. Each tool earns its place, covering the essential operations without unnecessary bloat.

Completeness4/5

Core workflows are covered: list sources, build index, search, read chunks, and write agent notes. A minor gap is the lack of a way to enumerate chunks or retrieve document structure, but this is workable for the intended use case.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Mirror Memory MCP Server
io.github.Tr1ckyMag1ca1
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Knowledge & Memory Search Note Taking
2
forkast-mcp-docs A
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42
trip2g B
io.github.trip2g
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
RAG Systems Note Taking Search
11238
hjarni AOAuth
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Note Taking Workplace & Productivity
383

Related MCP Servers

NOUZ MCP Server
Knowledge & Memory Note Taking
Semiotronika
A
license
A
quality
A
maintenance
MCP Server for local knowledge management. Semantic + keywords + tags
Updated 13 days ago (2026-09-02 18:13 UTC)
8
155 PyPI
19
MIT
Hoard
Knowledge & Memory RAG Systems Agent Orchestration
thrr87
A
license
Not graded
quality
D
maintenance
Local MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.
Updated 7 months ago (2026-02-07 12:52 UTC)
4
MIT
DocGraph
Knowledge & Memory Search Documentation Access
Detective-XH
A
license
A
quality
C
maintenance
MCP server that indexes Markdown, Word, HTML, and PDF documents into a SQLite knowledge graph with CJK+Latin full-text search and cross-document reference tracking. Runs drift audits to surface stale policies, conflicting research claims, superseded ADRs, and undocumented code exports.
Updated 9 days ago (2026-09-07 08:09 UTC)
10
8
MIT
md-graph
Knowledge & Memory Search File Systems
LZMW
F
license
Not graded
quality
C
maintenance
MCP server that enables full-text search and link navigation over Markdown files as a knowledge graph.
Updated 3 months ago (2026-06-04 05:51 UTC)
-