merlin-perceval-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GITHUB_TOKEN | No | Raises the GitHub API rate limit. Rarely needed: the server makes at most a couple of API calls per repository per hour, and reads all file contents through raw.githubusercontent.com, which is not rate limited. | |
| MERLIN_MCP_TIMEOUT | No | HTTP timeout in seconds. | 30 |
| MERLIN_MCP_CACHE_TTL | No | Seconds to cache indexes and inventories. | 3600 |
| MERLIN_MCP_LOG_LEVEL | No | Logging level. Logs go to stderr, leaving stdout free for the protocol. Also settable with --log-level. | WARNING |
| MERLIN_MCP_NOT_FOUND_TTL | No | Seconds to remember a 404. Kept short so a page missing during a docs redeploy is not reported as absent for the whole cache lifetime. | 60 |
| MERLIN_MCP_MERLIN_VERSION | No | Pin the MerLin docs version, e.g. 0.3. | auto-discovered |
| MERLIN_MCP_PAGE_CACHE_TTL | No | Seconds to cache pages and source files. | 900 |
| MERLIN_MCP_PERCEVAL_VERSION | No | Pin the Perceval docs version, e.g. v1.1. | auto-discovered |
| MERLIN_MCP_MAX_RESPONSE_BYTES | No | Hard cap on any single response body, and on inventory decompression. | 33554432 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_docsA | Search the documentation full text and return the best-matching pages. Use this first for conceptual questions ("how does angle encoding work", "noisy simulation", "remote execution on a QPU"). Each result gives a page name to pass to get_doc_page. Args: query: free text, e.g. "train a quantum layer on MNIST". library: "merlin" (default) or "perceval". limit: maximum number of pages to return. version: docs version override; defaults to the version upstream currently publishes. |
| get_doc_pageA | Read one documentation page in full. Accepts a page name from search_docs ("user_guide/layer"), or a documentation URL. Returns the page's published reStructuredText source, so code blocks and directives survive intact. Long pages are windowed; the footer tells you the next offset. Args: page: page name or URL. library: "merlin" (default) or "perceval". version: docs version override. offset: character offset to start from. limit: maximum characters to return. |
| search_apiA | Find documented API symbols by name. Searches the project's own symbol inventory, so it covers every documented class, function, method, module, attribute and property. Use it to discover exact dotted names, then call get_api_doc for signatures. Args: query: part of a symbol name, e.g. "QuantumLayer", "encode", "detector". library: "merlin" (default) or "perceval". kind: restrict to one of class, function, method, module, attribute, property, data. limit: maximum number of symbols to return. version: docs version override. |
| get_api_docB | Get the exact signature and docstring of one API symbol. Accepts a fully qualified name ("merlin.algorithms.layer.QuantumLayer") or a bare one ("QuantumLayer"). The signature is parsed from the library's real source, so it reflects the code that will actually run, and is paired with the documentation URL. Args: symbol: class, function, method or module name. library: "merlin" (default) or "perceval". version: docs version override, used for the documentation link. |
| get_sourceA | Read the library's real source code. Given a dotted symbol the result is narrowed to that class or function; given a module name the whole module is returned. Use this when the documented behaviour is ambiguous and you need to see what the code does. Args: target: dotted symbol or module, e.g. "merlin.core.circuit" or "QuantumLayer". library: "merlin" (default) or "perceval". ref: git ref to read; defaults to the repository's default branch. offset: character offset to start from. limit: maximum characters to return. |
| list_examplesA | List the runnable example notebooks shipped with the library. For MerLin this includes the curated gallery — quickstarts, model families and the reproduced-paper implementations — each with a one-line summary and tags. Pass a name from here to get_example. Args: library: "merlin" (default) or "perceval". topic: filter on title, summary or tag, e.g. "kernel", "MNIST", "reservoir". |
| get_exampleA | Read an example notebook as markdown with runnable code cells. This is the fastest way to get correct, working code: the notebooks are maintained against the current release. Cell outputs are omitted unless you ask for them. Args: name: example name from list_examples, e.g. "notebooks/FirstQuantumLayers". library: "merlin" (default) or "perceval". include_outputs: also include printed output of each code cell. version: docs version override. offset: character offset to start from. limit: maximum characters to return. |
| get_release_notesA | Read the most recent upstream release notes. Useful for "what changed", "is this API still current" and migration questions: these libraries move fast and the release notes are where breaking changes are described. Args: library: "merlin" (default) or "perceval". limit: how many releases to include, newest first. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| merlin_quickstart | Draft a plan for writing code against MerLin or Perceval, grounded in the docs. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
Tools cleanly pair as search+read for three resource types (docs, API symbols, examples) plus source and release notes, and descriptions explicitly differentiate them. The only mild overlap is deciding between get_doc_page, get_api_doc, and get_source when exploring a concept, but each targets a distinct content type (prose docs, signature/docstring, raw code).
Every tool follows a consistent snake_case verb_noun pattern: search_docs, get_doc_page, search_api, get_api_doc, get_source, list_examples, get_example, get_release_notes. The verbs (search/get/list) map predictably to the action performed with no convention mixing.
Eight tools is well-scoped for a two-library documentation retrieval server, with each tool earning its place (search+read for docs/API/examples, plus source and release notes). Nothing feels redundant or padded.
The surface covers the full research lifecycle: conceptual doc search/read, exact API symbol discovery and signatures, raw source for verifying behavior, runnable examples, and release notes for migration. This is a complete knowledge-retrieval toolkit with no obvious dead ends.