Taskflow Doc Search

io.github.cynthiawang109-sudoPublished by GitHub account cynthiawang109-sudov0.1.1Updated Nov 15, 2026

Search local TaskFlow workspace documentation and read tickets over MCP stdio.

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Local MCP server that lets an assistant search a TaskFlow workspace's Markdown docs three ways, read documents, and list or draft tickets.

What you can do
  • Search docs by keyword, TF-IDF similarity, or local sentence embeddings, with path, title, score and snippet
  • Fetch a single Markdown document by workspace-relative path, limited to projects/ and tickets/
  • List archived tickets from tickets/ with an optional status filter
  • Propose a new ticket as a draft file under tickets/drafts/
When to use it
Useful when an AI coding agent should answer questions from a local documentation and ticket workspace instead of guessing, and when you want a draft-first path for filing new tickets that a human later promotes.
Requirements
Runs locally over stdio, installed from PyPI with uvx or pip (Python). Requires AI_WORKSPACE_ROOT set to the absolute path of the workspace containing projects/ and tickets/. Keyword and TF-IDF search need no network; embeddings download a model once and need the optional embeddings dependencies, with DOC_SEARCH_EMBEDDING_MODEL to override the default model.
Before you install
propose_ticket writes new files under tickets/drafts/ and is annotated as a write, so clients may prompt before calling it; it cannot modify or delete existing tickets. Embeddings write a derived cache in the server's .index/ directory and download a model on first use. No credentials are used and the server does not call GitHub.

Installation

In SourceWeft

  1. Open Taskflow Doc Search in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

doc-search MCP server

A small MCP server written with FastMCP. It gives an AI coding agent structured access to this workspace's documentation and demo tickets — the local, public stand-in for the Jira/Confluence side of the original production workspace. Five tools are annotated read-only (embeddings maintains a derived local cache); the sixth can only write ticket drafts (see below).

Tools

ToolWhat it does
search_docs(query, limit=8)Keyword search across every Markdown doc under projects/; title hits ×3, heading hits ×2, body hits ×1; returns path, title, score, snippet
search_docs_semantic(query, limit=8)TF-IDF vector-space search over the same corpus (cosine similarity); returns path, title, score (0–1), snippet
search_docs_embeddings(query, limit=8)Sentence embeddings over heading chunks; returns path, title, cosine score, snippet, heading; caches in .index/
get_doc(path)Fetch one document by workspace-relative path (only projects/ and tickets/ are readable)
list_tickets(status?)List the pre-TF-115 archive from tickets/*.md front matter, optionally filtered by status
propose_ticket(title, body, priority="medium")Write a ticket draft to tickets/drafts/draft-<slug>.md — the server's only source-content write; it cannot create or modify real tickets

Draft-first writes

propose_ticket mirrors the production workspace's rule for outward writes (there: Jira changes start as drafts a human approves). The boundary is enforced by the tool, not by politeness: it writes only new files under tickets/drafts/, always with status: draft, it refuses to overwrite an existing draft, and it is annotated as a write, so clients ask the user before calling it. tickets/ is the pre-TF-115 archive; list_tickets never shows drafts as tickets. A human reviews and promotes a draft with scripts/promote-draft.ps1 (or .sh), which files an Issue instead of moving the file into tickets/. Set AI_WORKSPACE_PROJECT to the workspace Project number, or pass -Project N / --project N, to also add the Issue to the board. Without a Project, the script prints the Issue URL and notes that it was not added to a board. The draft is preserved. The doc-search server stays credential-free and never calls GitHub.

Three rungs of document search

  1. search_docs counts exact term hits with title/heading/body weights. It is predictable for known terms, but repetition can dominate ranking.
  2. search_docs_semantic uses TF-IDF cosine similarity over whole documents. It down-weights common terms and balances multi-term queries. Both of these first two rungs are bag-of-words models: neither understands synonyms. They use only the standard library and rebuild their vectors per call.
  3. search_docs_embeddings uses sentence-transformers over ATX heading sections, embedding the document title, heading trail and body. It can retrieve paraphrases and synonyms, but relevance is model-dependent. Cosine ranking uses pure Python. A content-hash fingerprint invalidates the derived .index/ cache when documents or the model change.
  • Local documents: searches never modify the source documents. Embeddings writes a derived cache; propose_ticket writes drafts under the rules above.
  • No credentials: keyword and TF-IDF need no network. Embeddings downloads its model once, then runs fully locally.
  • Client-agnostic: plain MCP over stdio.

Setup

powershell
cd mcp\doc-searchpython -m venv .venv.venv\Scripts\python -m pip install -r requirements.txt pytest

Optional embeddings dependencies (includes torch):

powershell
.venv\Scripts\python -m pip install -r requirements-embeddings.txt

DOC_SEARCH_EMBEDDING_MODEL overrides the default sentence-transformers/all-MiniLM-L6-v2. DOC_SEARCH_EMBEDDER=fake selects only a deterministic hashed-token test double, without semantic understanding.

Evaluate the synced corpus with python scripts/run_eval.py; add --write to record the dated results in EVAL.md. The eval is not run in CI.

Run the tests

powershell
.venv\Scripts\python -m pytest

The tests build a throwaway fixture workspace, so they pass whether or not sync has populated projects/.

Register it

Codex — add to ~/.codex/config.toml:

toml
[mcp_servers.doc-search]command = 'C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe'args = ['C:\path\to\ai-workspace-kit\mcp\doc-search\server.py']

Claude Code:

powershell
claude mcp add doc-search -- C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe C:\path\to\ai-workspace-kit\mcp\doc-search\server.py

The server finds the workspace root from its own location (<root>/mcp/doc-search/server.py); set AI_WORKSPACE_ROOT to override.

Install the distribution

Once published, install with pip install taskflow-doc-search (or pip install "taskflow-doc-search[embeddings]" for sentence embeddings). For a local checkout, pip install . from this directory works today. Run taskflow-doc-search with AI_WORKSPACE_ROOT set to the absolute path of the workspace to search. It serves MCP over stdio; no command arguments are needed. The existing python server.py launcher and its automatic workspace-root detection remain supported.

Release instructions: PUBLISHING.md. The included server.json is prepared for an optional MCP registry listing and has not been published.

Source: mcp/doc-search/README.md at commit e3a66ed

Tools

6

search_docs

Search Docs

Keyword search over the workspace documentation repos. Ranking is deliberately simple and inspectable: a hit in a document title counts 3, in a heading 2, in body text 1. Returns workspace- relative path, title, score, and the first matching line as a snippet.

Parameterslimitqueryrequired

search_docs_semantic

Search Docs Semantic

Vector-space (TF-IDF, cosine similarity) search over the docs. The contrast with search_docs is deliberate. Keyword search counts exact hits with hand-set weights (title x3, heading x2, body x1), so a document that repeats a common term many times can outrank the topically closest one. Here each document is a TF-IDF vector: terms that appear in many documents (low information) are down-weighted by the IDF factor, and ranking is by cosine similarity to the query vector, i.e. overall topical closeness across all query terms. It is still a bag-of-words model - no synonym or embedding magic. Pure stdlib; the corpus is re-indexed on every call, which is fine at documentation-repo scale and keeps the server stateless.

Parameterslimitqueryrequired

search_docs_embeddings

Search Docs Embeddings

Search document sections using locally computed sentence embeddings. Returns path, title, cosine score rounded to four places, the first non-empty body line (up to 200 characters) as snippet, and heading trail. Writes only a derived cache in this server's .index/ directory. The optional model downloads on first use, then runs locally. Model imports are deferred until this tool is called, keeping startup torch-free.

Parameterslimitqueryrequired

get_doc

Get Doc

Fetch one Markdown document by workspace-relative path, e.g. "projects/taskflow-docs/system-overview.md" or "tickets/TF-101.md". Paths outside projects/ and tickets/ are refused.

Parameterspathrequired

list_tickets

List Tickets

List the pre-TF-115 archive (Markdown files in tickets/). Optionally filter by status: open, in-progress, done. New work lives in GitHub Issues; humans promote drafts via scripts/promote-draft.

Parametersstatus

propose_ticket

Propose Ticket

Propose a new ticket as a DRAFT under tickets/drafts/. Draft-first is enforced here, not left to convention: this is the server's only write tool, and it can only create a new file in tickets/drafts/ with status "draft". It cannot create, modify, or delete the pre-TF-115 archive in tickets/. A human reviews the draft and files an Issue via scripts/promote-draft if it should become a ticket. The server stays credential-free. Returns the workspace-relative path.

Parametersbodyrequiredtitlerequiredpriority

Version history

1
  1. v0.1.1LatestNov 15, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts