{"report":{"v":1,"package":"@matthiasnordwig/matrix-mcp","version":"0.2.8","ranAt":"2026-11-16T11:47:44.347Z","install":{"ok":true,"integrity":"sha512-2lFZjKwrKL0nrfnzVOhP9N6qE7XKeh/Bc8bksQ3NR8UG/Xvm/jrpKWlvp3FboqLaqcDYlZTunvMz5EEg699TlA==","deps":4,"scripts":[],"bins":["matrix-mcp"],"license":"MIT","engines":"node >=18","repository":"git+https://github.com/matthiasnordwig/matrix-mcp.git","bin":"matrix-mcp"},"start":{"ok":true,"ms":76,"serverName":"matrix","serverVersion":"0.2.8","protocol":"2025-06-18","stderr":"matrix-mcp-stdio 0.2.8: data /tmp/.local/share/matrix-mcp · groups read,documents,profiles,grid,models · LLM: endpoint 1 'client' (answered by the calling agent via llm_tasks) · shared folders: none yet (add_files asks the user)\nmatrix-mcp-stdio: embedding model: embeddinggemma-2 (download ~1.2 GB on request) — not installed — asks the user before downloading ~1.2 GB\n[info] mcp: list_contexts  → ok (0 ms)\n[info] mcp: get_status  → ok (0 ms)\n[info] mcp: list_grid_profiles  → ok (0 ms)\n[info] mcp: list_grid_runs  → ok (0 ms)\n[info] mcp: search_embedding_models  → ok (365 ms)\n"},"tools":[{"name":"list_contexts","description":"List all Matrix contexts (local document collections, e.g. regulations, legal norms, contracts, manuals). For each: id, name, the user's description of what the collection contains, document and chunk counts, chunking strategy, the bound embedding model (needed for semantic search) and the languages of its documents (ISO codes, most documents first). Start here, then search a context and fetch the cited chunks.","params":[]},{"name":"list_documents","description":"List the documents (files) of one Matrix context: id, name, the optional per-file description, size, page count, number of chunks and language (ISO code). Does not return the document text — use the search and chunk tools for content.","params":["context_id"]},{"name":"job_status","description":"Poll a long-running Matrix job (ingest, chunking, embedding, graph extraction …) started by another tool that returned a job_id. Returns state (running | done | failed), progress, result and error. Finished jobs stay pollable for about 10 minutes.","params":["job_id"]},{"name":"search_context","description":"Semantic + keyword (hybrid) search over the original text of one or more Matrix contexts — the default tool for finding passages in the user's documents (regulations, legal norms, contracts, standards, manuals). Returns numbered chunks with stable chunk_id, header (document · outline path, e.g. chapter › article › paragraph, where headings are recognised), file and page where known, text and outgoing references to other norms (with the resolved target chunk_id when known) — cite sources by chunk_id (and file/page for the user). In this program each hit is an excerpt of about 300 characters that fits the query, not the whole passage, and hits of one article are merged into one entry with several chunk_ids and pages: quote and cite only what you read with get_chunks (whole article: get_section); detail \"full\" returns whole passages. get_section returns the whole article or section of a hit. Requires the context to have an embedding model (see list_contexts); otherwise use lookup_exact. Each chunk carries its language (ISO code; list_contexts lists the collection's). Search finds best in the language of the documents: if the question is in another language, also search with a translation into theirs. Narrow to mails of one sender, a date range or a folder with sender, date_from/date_to and folder (e.g. what X wrote in autumn 2001).","params":["context_ids","date_from","date_to","detail","document_ids","folder","query","rerank_candidates","sender","top_k"]},{"name":"lookup_exact","description":"Exact-phrase keyword search over the original text. Use it instead of search_context for exact identifiers and citations that vector search blurs: legal norms and article numbers ('Art. 33', '§ 25a KWG', '2016/679'), defined terms, quotes. Terms must appear adjacent and in order. Same result format as search_context; works without an embedding model.","params":["context_ids","date_from","date_to","document_ids","folder","sender","term"]},{"name":"get_chunks","description":"Fetch specific chunks by chunk_id to read the exact source text for a citation, or to follow an outgoing reference (resolved_chunk_id) from another chunk. A fragmented section/article is completed with up to two continuation chunks automatically. Ids outside the given contexts/documents are not returned (reported in missing_ids). A chunk that runs onto another PDF page has `page_end`, and its text marks each page change with a line [p. N]: cite the page of the sentence you quote (text before the first mark is on `page`).","params":["context_ids","document_ids","ids"]},{"name":"get_section","description":"Fetch the whole article or section a chunk belongs to (the chunk's neighbours up to the next heading of the same or a higher rank, e.g. all of Art. 18 for a hit in Art. 18(1)), with full text, pages (page changes inside a chunk marked [p. N]) and the outline path. Use it before answering from a rule that may have exceptions, conditions or special cases in other paragraphs, instead of relying on the single hit. A long section is cut to about 12,000 characters around the chunk and the chunk_ids left out are listed (fetch them with get_chunks); without recognised headings only the chunk itself comes back.","params":["chunk_id","context_ids","document_ids"]},{"name":"find_citing_chunks","description":"Reverse reference lookup: find chunks whose text CITES a given legal norm ('Art. 395 CRR', '§ 25a KWG', 'Art. 28 DORA') — useful when a provision applies to an entity via a reference or range list that neither search_context nor lookup_exact surfaces. Optional query soft-ranks many citing chunks by semantic similarity. Same result format as search_context.","params":["context_ids","document_ids","norm","query"]},{"name":"list_norm_references","description":"List the legal-norm references Matrix recognized in a context's text ('§ 25a KWG', 'Art. 28 DORA', 'AT 4.3 MaRisk' - normalized keys): without chunk_ids every referenced norm with how many chunks cite it and the first chunk ids, most cited first (an overview of what a collection depends on); with chunk_ids the references of exactly those chunks (follow a passage's cross-references, then lookup_exact or find_citing_chunks for the targets). contains filters the keys.","params":["chunk_ids","contains","context_id","limit"]},{"name":"get_page_image","description":"Return the stored image (JPEG) of one graphics page - an organigram, chart or diagram that Matrix keeps as a picture next to the document text - together with document name, page number and size. Use the `page_image_id` of a search hit (a chunk marked found_via_page_image) to look at the page that made it relevant, e.g. to read a figure the extracted text does not contain. Unknown id = error.","params":["page_image_id"]},{"name":"get_status","description":"Live status of Matrix' background work — chunking, embedding and knowledge-graph extraction progress (active, done/total, errors, current phase) — plus the most recent application log lines (errors, warnings, MCP calls). Use it to follow long-running ingestion or graph jobs and to diagnose failures; for one specific job use job_status. This program adds shared_folders (what Matrix may read, with problems such as a folder that does not exist), search_model (state of the search model and the date of its recommendation), model_task_queue (tasks waiting for you) and running_jobs.","params":["log_lines","min_level"]},{"name":"verify_citations","description":"Check the citations of YOUR OWN answer against the cited source chunks — Matrix' citation attribution check for answers about documents, regulations and legal norms. Pass the answer text and `chunk_ids`; mark every claim with [n] = n-th entry (1-based) of chunk_ids, or with [chunk:<id>] (the id is added to the list). Answers without markers are rejected. Also list the retrieved chunks you did NOT cite: they are the candidates a better source is searched among. Per citing statement and marker the verdict is `supported` (verbatim quote found, or the cited/co-cited chunk carries at least 30% of the statement's weighted key terms — a plausibility check, NOT proof that the chunk states the claim), `better_candidate` (another listed chunk carries it — term overlap and embedding similarity agree; see alt_chunk_id), `suspect` (another chunk looks better on term overlap only, or a quoted text is not in the cited chunk; `embedding_issue` says why the embedding check could not run) or `not_judged` (too little content, or weak overlap with no better chunk to compare — NOT a confirmation). A quote that exists only in an AI-generated image description is no source text: its citations have `quote: found_in_generated_description` and are counted under `summary.from_generated_description`, never under `supported`. Each citation reports the cited chunk's context_id and document — check that it is the context you meant — and `page` (`page_end` over a page break): the PDF page a verified quote stands on, otherwise the cited chunk's pages. At most 100 citing statements are judged per call (`truncated` says how many were skipped). Embeddings are only compared within one embedding model.","params":["answer","chunk_ids"]},{"name":"list_sheet_tables","description":"List the spreadsheet tables of the given contexts: every table region of an uploaded Excel/ODS/CSV file is also stored as an SQL table. Returns per table its SQL name, document, sheet, row count and columns (SQL name, original header, type, notes such as 'percent, stored as a fraction', an example value). Use the names with query_table to compute exact sums, counts, averages or rankings.","params":["context_ids","document_ids"]},{"name":"query_table","description":"Run ONE read-only SQLite SELECT (WITH … SELECT allowed) over the spreadsheet tables of the given contexts (see list_sheet_tables) and get the result as CSV with a header line: exact aggregates (SUM, COUNT, AVG, MIN/MAX), filters, GROUP BY, window functions, date()/strftime(). Only those tables are readable; writes, PRAGMA, ATTACH and other tables are refused. At most 200 rows / 20,000 characters (truncation is reported), 2 s time limit.","params":["context_ids","document_ids","sql"]},{"name":"create_context","description":"Create a new, empty Matrix context (a document collection) and pass chunking_strategy \"structural\": PDFs are split along their layout (articles, headings, tables), other formats (Word, Excel, text, HTML) by their headings, with no language model. The configured search model is bound automatically; if it still has to be downloaded the answer says so: call setup_embedding_model, the user approves that call. Next: add_files.","params":["chunking_strategy","description","name"]},{"name":"embed_context","description":"Compute embedding vectors for a context's chunks with its bound embedding model, as a background job. By default only chunks without a vector are embedded (resume); reembed=true recomputes all vectors in place. Returns {job_id}; poll job_status. The context needs an embedding model (create_context / update_context).","params":["context_id","reembed"]},{"name":"embed_page_images","description":"Embed the stored graphics pages (charts, org charts, diagrams found while ingesting PDFs) of a context as image vectors, so text questions also find them (image search). Background job; by default only pages without a vector of the context's model, reembed=true recomputes all. Needs a local ONNX embedding model with a vision encoder; otherwise it fails with the reason. Returns {job_id}; poll job_status (result: total, embedded, failed). Status first: page_image_status.","params":["context_id","reembed"]},{"name":"cancel_page_image_embedding","description":"Stop the running embed_page_images job (there is one at a time) after the page it is on; page vectors written so far are kept, embed_page_images continues with the missing ones later. Returns {cancel_requested}.","params":[]},{"name":"page_image_status","description":"Graphics pages of a context for the image search: how many page images are stored (total), how many have a vector of the context's embedding model (embedded), and whether that model can embed images (vision_available).","params":["context_id"]},{"name":"set_document_description","description":"Set (or clear with null/empty) the short description of one document. Agents see it in list_documents and use it to decide which files to search.","params":["description","document_id"]},{"name":"list_profiles","description":"List Matrix profiles of one kind: chunking (LLM chunking prompt, window overlap), structural (regex patterns that split PDFs along headings/articles) or grid (grid question prompt and output format). Use an id with update_context to assign it to a context.","params":["kind"]},{"name":"create_profile","description":"Create a new chunking, structural or grid profile. `profile` holds that kind's fields. chunking: name, prompt (must contain {{pre_chunk}}), overlap_ratio, max_signature_len, metadata_fields (JSON text), match_strategy (exact_forward|fuzzy), fuzzy_threshold. structural: name, min_chunk_chars, max_chunk_chars, patterns[{group_name, role, regex, flags, priority, label, sort_order}]. grid (a template = prompt + answer columns): name, system_prompt (the template's prompt, asked of every row), data_format (plain|json), json_schema ({mode: object|array, fields: [{key, type: string|number|integer|boolean|date|enum, description, enum_values?, optional?}]}). Returns the stored profile.","params":["kind","profile"]},{"name":"update_profile","description":"Change an existing chunking, structural or grid profile. Only the fields given in `profile` change (same field names as create_profile; for a structural profile `patterns`, if given, replaces the whole list). Contexts using the profile pick the change up on their next run. Returns the stored profile.","params":["kind","profile","profile_id"]},{"name":"update_context","description":"Change a Matrix context's name, description, structural profile (list_profiles, kind structural) or embed_images (embed graphics pages automatically after the text; needs a search model with an image encoder). Only the fields you pass change; null clears an assignment. To move a context to another search model use setup_embedding_model with reindex_contexts.","params":["context_id","description","embed_images","name","structural_profile_id"]},{"name":"list_grid_profiles","description":"List the grid profiles (the templates of the app's Tables page). A template is a prompt plus answer columns: id, name, the template's prompt (field system_prompt; it is the instruction asked of every row), output format (plain text, or JSON whose fields become the answer columns: mode object = one answer per row, array = several entries per row). Pick one as grid_profile_id for run_grid.","params":[]},{"name":"list_grid_runs","description":"List earlier grid runs (newest first, at most 50): run_id, the question (prompt), when it last changed, and how it ran (model, tool_call_budget: 0 = classic, -1 = agentic until the row's context is full, > 0 = agentic with at most that many searches per row; template, context_mode; null for old runs). Read a run's table with grid_results.","params":[]},{"name":"run_grid","description":"Ask the same question about many rows and collect the answers as a table (the app's Tables page) - e.g. 'which obligations does this paragraph impose?' for every chunk of a regulation. Rows are the passages of a collection (source_context_id: all its documents, or only document_ids; max_rows caps them) or texts you give (row_texts: one row per text, e.g. search hits you picked). A row sees its own text, and further evidence only from retrieval_context_ids (matching passages of those contexts, retrieved per row). Each row is answered by the LLM (by you, the calling agent: llm_tasks / llm_answer). The template (grid_profile_id) gives the prompt and the answer columns; your prompt, if given, replaces the template's prompt. The run continues in the background: returns {run_id, rows} at once; where the app is open, show_in_app (where offered; review_run + run_id) brings the table in front of the user; stop it with cancel_grid_run. To only put a collection's passages on the Tables page without asking anything, use show_in_app (where offered) with target table_rows. Every row is one model task for you; with many rows it uses a lot of the user's Claude quota - say how many before you start.","params":["document_ids","follow_refs","grid_profile_id","hybrid","max_rows","prompt","reasoning","rerank","retrieval_context_ids","retrieval_prompt","row_texts","source_context_id","tool_call_budget","top_k"]},{"name":"grid_results","description":"Read a grid run as a table: columns = row (chunk id) + status + the answer fields (JSON profiles; an answer with several items becomes several table rows) or a 'response' column (plain profiles), rows = the answers, cells shortened. Also reports the status counts and whether the run is finished. Rows of a run that has just started are still queued or running; the user watches them fill in on the Tables page (show_in_app, where offered; review_run). If you need the finished table in this answer, set wait_seconds: the call returns as soon as the run is finished or the time is up.","params":["max_cell_chars","max_rows","run_id","wait_seconds"]},{"name":"cancel_grid_run","description":"Ask a running grid run to stop: rows not yet started end as 'Cancelled', answers in flight still arrive. Rows already answered are kept.","params":["run_id"]},{"name":"suggest_grid_columns","description":"Let the model propose the answer columns for a table prompt, as the Tables page's \"Suggest from prompt\" does: every question the prompt asks becomes a column (key, label in the prompt's language, type string|number|integer|boolean|date|enum, description); mode object = one answer per row, array = a list per row. Background job: returns {job_id}; the job_status result is a json_schema ({mode, fields}) to put into a grid profile (create_profile kind grid, data_format json) before run_grid. Uses the model selected for tables unless llm_id/pool_id is given - in the stand-alone program the 'client' endpoint, i.e. you answer it via llm_tasks.","params":["prompt"]},{"name":"search_embedding_models","description":"Find embedding models (search models) on Hugging Face that Matrix can run locally: feature-extraction repos with an ONNX export. Per repo: downloads, likes, license, languages (as the model card states them), created/last-modified dates, vector size (dimension; null = not stated, cannot be registered automatically), query/document prefixes, its graph variants with download size (e.g. model = full precision, model_q4 = int4) and image encoders (graphics search). Use it when the user asks for a better or smaller search model, or when the configured recommendation is older than six months (get_status shows its date, search_model): compare the candidates with the current model and suggest one - multilingual documents need a multilingual model. Install: setup_embedding_model with repo_id and variant. Reaches the internet; nothing is downloaded.","params":["limit","query","sort"]},{"name":"add_files","description":"Add a local file, or every supported file of a local folder (recursively by default), from the user's computer to a Matrix context as ONE background job: extract text, chunk, embed if the context has an embedding model. Only paths inside the folders Matrix may read are allowed: the folder Claude Code was started in, folders from the plugin settings and folders the user allowed (list_allowed_folders). For any other path the user is asked and decides - tell them in words first which folder and why; never try to get around a refusal. A symlink or `..` counts by where it leads; symlinked folders inside a folder are not followed; hidden files and folders are skipped. Formats: pdf (scans are read by text recognition), Office, OpenDocument, mail, html, text/markdown, csv, images, zip, ...; max 64 MB per file, up to 500 files per call. Use an absolute path. Returns {job_id, files_queued, files, skipped}; poll job_status (result: docs_created, chunks_staged, chunks_from_scanned_pages, attachments_from_mail_text (attachments found only as text inside a mail, e.g. in a returned mail: tell the user), embedded, skipped per file, files_total, files_read, chunking). Files already in the context are skipped; from then on Matrix keeps the context up to date with this file or folder by itself (new and changed files are read again before searches, deleted ones are marked missing).","params":["context_id","path","recursive"]},{"name":"setup_embedding_model","description":"Download and register the search model (embedding model; search by meaning needs it) as a background job: returns {job_id}; poll job_status until it is done, then repeat the call that asked for the model. Without arguments: the model this server is configured with - by default EmbeddingGemma 2 (multilingual, text and images, recommended October 2026), a one-time download of about 1.2 GB from Hugging Face. Call it when a tool says the model is missing: the user approves this tool call, which is their consent - tell them the size. Nothing is downloaded otherwise. If the recommendation is older than six months (get_status shows search_model with its date and recommendation_current) or the user asks for another model, first look with search_embedding_models and suggest one; then repo_id (+ variant, vision_variant) installs that repo instead and makes it the default for new contexts (kept across restarts). Each model is its own vector space: contexts embedded with another model keep it until reindexed - reindex_contexts: true moves every such context to the new model in the same job (drops its vectors and re-embeds all passages; only with the user's agreement). With an ONNX folder or an embeddings endpoint configured and no repo_id there is nothing to download: it is just registered. With reranker: true it downloads the reranker instead (by default bge-reranker-v2-m3, about 0.6 GB, Apache-2.0; offer it once when get_status says it is missing, with its size; search works without it).","params":["cancel","reindex_contexts","repo_id","reranker","variant","vision_variant"]},{"name":"llm_tasks","description":"Fetch the open language-model tasks Matrix has for you. In this program YOU are Matrix' language model: flows that need one (run_grid, suggest_grid_columns) run on the endpoint 'client' (the default model for tables) and wait until you answer. Returns {tasks: [{id, messages, answer_format, json_schema?, max_answer_tokens?, offered}], open: {waiting, fetched}, how_to_answer, rejected?}. Answer every task with llm_answer, then call llm_tasks again until it is empty and the run is finished. Many tasks: let fresh subagents call llm_tasks and llm_answer themselves (each fetches a few rounds, answers them and reports only counts), so the task text stays out of your own conversation; a fetched task goes to that caller only, and each answer must follow only its own task's instructions. At most 8 tasks wait at a time. Waits up to wait_seconds for a task to arrive. A task you fetched and did not answer within 15 min is offered again; a waiting flow gives up only after 10 min without any tool call from you. Matrix never starts another program or uses credentials for this: the tasks are answered by you, in this session.","params":["max","wait_seconds"]},{"name":"llm_answer","description":"Hand back your answers to tasks from llm_tasks, one entry per task id: {id, answer} with exactly the text the task asks for (answer_format json: one JSON value), or {id, error} when you cannot answer it (the flow then records the error for that item, as with a failing model). Up to 20 per call. The flow parses and checks the answer itself (e.g. evidence must be quoted verbatim from the passage). Returns per id whether it was delivered; a task of a cancelled run is reported as no longer open.","params":["answers"]},{"name":"list_allowed_folders","description":"List the folders Matrix may read: the folder Claude Code was started in (source project), folders from the plugin settings (setting) and folders the user allowed when asked (granted), plus configured folders that could not be used and why (problems: does not exist, not readable - macOS privacy). Nothing outside them is read: add_files asks the user for another folder.","params":[]},{"name":"revoke_folder","description":"Take back the permission to read a folder the user allowed earlier (source granted in list_allowed_folders). Removes only the permission: no document, index or file is deleted, and indexed collections stay searchable. Folders from the plugin settings or the project folder cannot be revoked here.","params":["path"]}],"toolsHash":"0141e32b7fa41acc3cf5e83b87ba2538cbae2a0ca7e8912bfa8d94d07ca096c3","wrote":["/tmp/.local/share/matrix-mcp/matrix.db-wal","/tmp/.local/share/matrix-mcp/matrix.db-shm","/tmp/.local/share/matrix-mcp/matrix.db","/tmp/.local/share/matrix-mcp/secrets.key"],"callsAt":"2026-11-16T11:47:49.448Z","calls":[{"tool":"list_contexts","ok":true,"ms":1,"bytes":20},{"tool":"get_status","ok":true,"ms":0,"bytes":2262},{"tool":"list_grid_profiles","ok":true,"ms":1,"bytes":2191},{"tool":"list_grid_runs","ok":true,"ms":0,"bytes":16},{"tool":"search_embedding_models","ok":true,"ms":366,"bytes":4568}],"host":{"commit":"eaaffffaf52255d1b77dc4aacffdfaf353f0c12c","run":"https://github.com/itsHaddad/bragproof/actions/runs/43857070216"},"network":{"names":["registry.npmjs.org"],"conns":[],"callNames":["huggingface.co"],"callConns":[]}},"summary":{"outcome":"started","needs":[],"contacts":[],"flags":[],"tools":37,"wrote":4,"callsTried":5,"callsAnswered":5,"callContacts":["huggingface.co"]},"history":[{"package":"@matthiasnordwig/matrix-mcp","version":"0.2.8","ranAt":"2026-11-16T11:47:44.347Z","outcome":"started","tools":37,"contacts":0,"flags":0,"serious":0,"toolsHash":"0141e32b7fa41acc3cf5e83b87ba2538cbae2a0ca7e8912bfa8d94d07ca096c3"}],"page":"https://bragproof.smaverk.com/r/%40matthiasnordwig/matrix-mcp"}