io.github.cynthiawang109-sudo由 GitHub 账号 cynthiawang109-sudo 发布v0.1.1更新于 Nov 15, 2026
Search local TaskFlow workspace documentation and read tickets over MCP stdio.
本地 MCP 服务器，让助手用三种方式检索 TaskFlow 工作区的 Markdown 文档、读取文档，并列出或起草工单。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
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).
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.
search_docs counts exact term hits with title/heading/body weights.
It is predictable for known terms, but repetition can dominate ranking.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.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.propose_ticket writes drafts under the rules above.Optional embeddings dependencies (includes torch):
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.
The tests build a throwaway fixture workspace, so they pass whether or not
sync has populated projects/.
Codex — add to ~/.codex/config.toml:
Claude Code:
The server finds the workspace root from its own location
(<root>/mcp/doc-search/server.py); set AI_WORKSPACE_ROOT to override.
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.
来源：mcp/doc-search/README.md，提交 e3a66ed
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.
limitquery必填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.
limitquery必填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.
limitquery必填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.
path必填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.
statusPropose 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.
body必填title必填priority已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
cd mcp\doc-searchpython -m venv .venv.venv\Scripts\python -m pip install -r requirements.txt pytest.venv\Scripts\python -m pip install -r requirements-embeddings.txt.venv\Scripts\python -m pytest[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 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