Skip to main content
Glama

knowflow

TypeScript Node MCP License

Documentation has always been a knowledge layer. knowflow makes it one that AI can actually reach.

knowflow is an MCP (Model Context Protocol) server built by an information architect who got tired of context-switching between four tools to answer one question: what are users not finding?

It connects a documentation corpus, GA4 search analytics, a Jenkins CI pipeline, and a RAGAS-style evaluation layer to Claude, in a single conversation.

Runs with no credentials. The corpus, GA4 analytics, Jenkins data, and evaluation all ship as working local implementations, so you can clone, build, and query it in about two minutes. Every one has a documented upgrade path to live data. See Upgrading to live data.

Claude Desktop / Claude Code
        │
        │  JSON-RPC over stdio
        ▼
   knowflow
        │
        ├── search_docs          → TF-IDF corpus search (upgradeable to pgvector / ChromaDB)
        ├── get_topic            → Full topic content by ID
        ├── list_topics          → Corpus index with product and type filters
        ├── get_content_gaps     → GA4 zero-result queries → ranked content gap list
        ├── get_build_status     → Jenkins publish pipeline status
        └── evaluate_pipeline    → RAGAS-style eval: relevance · faithfulness · recall

Demo


Related MCP server: Synaptex

Why this exists

Every documentation team asks the same question: what should we write next?

The answer used to live in three or four separate places: search analytics in GA4, existing content in a docs site, topic hierarchy in a spreadsheet, build status in Jenkins. Getting from "what are users not finding?" to "here is a drafted topic" took hours of context-switching.

knowflow collapses that into a single conversation.

get_content_gaps          "47 users searched for X and got nothing"
       ↓
search_docs               "nearest existing topic: rpm-upgrade-8.0"
       ↓
get_topic                 "here is the full content as context"
       ↓
Claude drafts             the missing section in under two minutes
       ↓
evaluate_pipeline         "faithfulness: 0.91 · relevance: 0.87 · recall: 0.74"
       ↓
IA reviews → publishes → gap closes → loop repeats

The part that changed most is not the speed. It is the signal. You know what to write before a support ticket tells you.


What you can ask Claude once connected

"What are the top ten search queries from the last 30 days that returned no results?"

"Run evaluate_pipeline with report_format markdown. Show me which queries are underperforming and why."

"Find every topic in the corpus that mentions the Tableau connector. Did the docs build pass today?"

"A user searched for 'silent RPM install' 47 times and got nothing. Find the nearest existing topic and draft the missing section."

"Which topics have not been reviewed in over 90 days? Flag them as potential faithfulness risks."


Quick start

1. Clone and install

git clone https://github.com/Bipin-24/knowflow.git
cd knowflow
npm install
npm run build

2. Connect to Claude Desktop

Open your Claude Desktop config:

OS

Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Add this block:

{
  "mcpServers": {
    "knowflow": {
      "command": "node",
      "args": ["/absolute/path/to/knowflow/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You should see knowflow in the tools list.

3. Connect to Claude Code

Drop a .mcp.json in your project root:

{
  "mcpServers": {
    "knowflow": {
      "command": "node",
      "args": ["../knowflow/dist/index.js"]
    }
  }
}

Tools

search_docs

Keyword search across the documentation corpus, ranked by TF-IDF. Upgradeable to embedding-based semantic search. See Architecture.

query    string   required   Natural language search query
product  string   optional   analytics-engine | ingres | actian-client | all
version  string   optional   e.g. "8.0", "11.x"
limit    number   optional   1–10, default 5

get_topic

Retrieve full Markdown content of a topic by ID.

topic_id  string  required  Topic ID from search_docs results

list_topics

Browse the corpus index with optional filters.

product     string  optional  analytics-engine | ingres | actian-client | all
topic_type  string  optional  concept | task | reference | troubleshooting | all

get_content_gaps

Surface search queries that returned zero or few results, meaning content your users need but that does not exist yet.

days          number  optional  Lookback window, default 30
limit         number  optional  Max gaps to return, default 20
min_searches  number  optional  Minimum search volume, default 2

Returns each gap with gap_type (missing_content or low_discoverability), nearest existing topic, search volume, and recommended action.

get_build_status

Check Jenkins CI/CD publish pipeline status.

job  string  optional  Jenkins job name, default "actian-docs-publish"

evaluate_pipeline

Run a RAGAS-style evaluation across the pipeline.

queries        string[]  optional  Test queries. Uses a default set of 10 if omitted.
report_format  string    optional  summary | detailed | markdown  (default: summary)

Metric

What it measures

Answer relevance

Does retrieved content answer the query?

Faithfulness

Are claims grounded in the source corpus?

Context recall

Did retrieval surface the most useful content?

Scores are computed by deterministic heuristics rather than an LLM judge, so the tool runs offline and returns the same result every time. That makes it useful as a regression check on retrieval changes. For production scoring, swap in the RAGAS Python library. See Evaluation.


Architecture

Ships with a lightweight TF-IDF engine, with no external dependencies or API keys. To upgrade to embedding-based semantic search:

  1. Add chromadb or pgvector to package.json

  2. Run scripts/index_corpus.py to embed the corpus

  3. Swap scoreTopics() in src/lib/search.ts for a vector similarity query

Evaluation

src/lib/evaluator.ts uses deterministic heuristics as a RAGAS approximation, so no LLM API calls are required to run it. Replace it with the RAGAS Python library for production use with an LLM judge.

Live data

Ships with realistic mock data for GA4 and Jenkins. To connect live sources:

cp .env.example .env
# Fill in BIGQUERY_PROJECT_ID, JENKINS_URL, JENKINS_TOKEN

The BigQuery SQL for GA4 Site Search export is in scripts/ga4_export.sql.


Project structure

knowflow/
├── src/
│   ├── index.ts                  # MCP server — tool registry and router
│   ├── tools/
│   │   ├── searchDocs.ts
│   │   ├── getTopic.ts
│   │   ├── listTopics.ts
│   │   ├── getContentGaps.ts
│   │   ├── getBuildStatus.ts
│   │   └── evaluatePipeline.ts   # RAGAS-style evaluation
│   ├── data/
│   │   └── corpus.ts             # Sample documentation topics
│   └── lib/
│       ├── search.ts             # TF-IDF search engine
│       └── evaluator.ts          # Evaluation engine
├── scripts/
│   └── ga4_export.sql            # BigQuery query for live GA4 export
├── .env.example
├── package.json
└── tsconfig.json

Upgrading to live data

What

Status

How to upgrade

Search

TF-IDF (built-in)

Swap for ChromaDB / pgvector

Content gaps

Mock GA4 data

Wire in BigQuery, see scripts/ga4_export.sql

Build status

Mock Jenkins data

Add JENKINS_URL and JENKINS_TOKEN to .env

Evaluation

Deterministic heuristics

Replace with the RAGAS Python library


Tech stack

  • Runtime: Node.js 18+ / TypeScript

  • Protocol: @modelcontextprotocol/sdk

  • Search: TF-IDF, upgradeable to pgvector / ChromaDB

  • Evaluation: Deterministic RAGAS approximation, upgradeable to RAGAS Python

  • Analytics: Mock GA4, upgradeable to BigQuery

  • CI: Mock Jenkins, upgradeable to the Jenkins REST API


  • docs-mcp — the base retrieval layer this evolved from: five MCP tools over a docs corpus, analytics, and CI

  • Documentation-AI-Assistant — RAG pipeline and chat UI over a documentation corpus

  • knowledge-graphs-for-ia — typed knowledge graph builder with relationship-based retrieval

  • IA Playbook — AI content governance framework for RAG-ready documentation


License

MIT. See LICENSE.


Author

Bipin Pandey — Principal Information Architect
Building the knowledge layer that humans and AI systems both depend on.

Portfolio · LinkedIn · GitHub

Available Tools

6 tools
evaluate_pipelineA

Run RAGAS-style evaluation on the RAG pipeline. Measures answer relevance, faithfulness, and context recall across a test query set.

ParametersJSON Schema
NameRequiredDescriptionDefault
queriesNoTest queries to evaluate. Uses default set if not provided.
report_formatNosummary

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only lists the metrics measured and mentions 'Run evaluation', but it does not indicate whether the tool is read-only, whether it modifies any state, what the output format looks like, or any side effects. This is insufficient for a tool with no annotation support.

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 two short sentences with clear structure, front-loading the purpose. Every word adds value, and there is no redundancy or filler.

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?

Given the tool's simplicity (two parameters, no output schema), the description covers the core purpose and metrics but omits details like expected output format, performance implications, or assumptions about the pipeline. It is minimally complete for an agent, but lacks behavioral context.

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

Parameters3/5

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

Schema coverage is 50% (only 'queries' parameter has a description). The description adds context by naming the metrics evaluated, suggesting how queries are used, but it does not provide additional meaning beyond the schema for 'report_format' (no description in schema or description). This is baseline adequate but not compensatory.

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 states it runs RAGAS-style evaluation on the RAG pipeline and lists the specific metrics measured (answer relevance, faithfulness, context recall). This differentiates it well from sibling tools like get_build_status or search_docs.

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 for evaluating a RAG pipeline on test queries, but it does not explicitly state when to use it versus alternatives, nor does it mention prerequisites or when not to use it. The sibling tools provide context, but no exclusions are given.

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

get_build_statusC

Check Jenkins CI/CD publish pipeline status.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobNoJenkins job nameactian-docs-publish

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as whether the tool is read-only, any side effects, or rate limits. For a tool that likely performs a read operation, this lack of transparency is a gap.

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

Conciseness4/5

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

The description is extremely concise at one sentence, which is efficient for a simple tool. However, it lacks structural elements like bullet points or separate sections for usage notes, which could improve scannability.

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?

Given the tool has no output schema and only one parameter, the description is minimally complete. However, it slightly lacks context about what the status output contains (e.g., success/failure, build number). Additional details would be helpful.

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

Parameters3/5

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

The input schema has 100% coverage with a default value and description for the only parameter. The description adds no additional meaning beyond the schema, but the schema is self-sufficient. Baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool's purpose: checking the status of a Jenkins CI/CD publish pipeline. It uses a specific verb ('Check') and resource, distinguishing it from siblings like 'evaluate_pipeline' which likely analyzes pipeline performance rather than just status.

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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or context. The single sentence does not help an agent decide if 'get_build_status' is appropriate compared to 'evaluate_pipeline' or other tools.

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

get_content_gapsA

Surface search queries that returned zero or low results — documentation your users need but doesn't exist yet.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoLookback window in days
limitNoMax gaps to return
min_searchesNoMinimum search volume

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, and the description lacks details about behavioral traits such as idempotency, permissions, or whether it modifies data. The description only indicates a read-only operation implicitly.

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, concise sentence that effectively conveys the tool's purpose without unnecessary words or repetition.

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?

Given the absence of an output schema, the description could provide more context about the return format or example results. However, for a simple retrieval tool with default parameters, the description is adequate but not complete.

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

Parameters3/5

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The tool description does not add additional semantic context beyond the schema, so a baseline score of 3 is appropriate.

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 states the tool's purpose with a specific verb ('surface') and resource ('search queries that returned zero or low results'), and provides context about solving a documentation need. It is distinct from sibling tools like 'search_docs' or 'list_topics'.

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 usage for finding content gaps but does not explicitly state when to use this tool versus alternatives, nor does it provide when-not-to-use guidance.

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

get_topicA

Retrieve full Markdown content of a topic by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
topic_idYesTopic ID from search_docs results

TDQS

A3.6/5.0
Behavior2/5

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

No annotations provided, so description must carry full burden. While it implies a read operation, it does not explicitly state read-only behavior, side effects, or other traits beyond the obvious retrieval.

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?

Single sentence with no unnecessary words. Concise and front-loaded with the action.

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 simple retrieval tool with one required parameter and no output schema, the description is sufficient. It covers what the tool does and what input is needed.

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

Parameters3/5

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

Schema coverage is 100% (topic_id described). The description adds no additional meaning beyond schema; baseline of 3 is appropriate.

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 states the action ('Retrieve'), resource ('full Markdown content of a topic'), and method ('by ID'). It distinguishes from sibling tools like list_topics and search_docs.

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?

No explicit when-to-use or when-not-to-use guidance. The schema parameter description hints at a workflow (use with search_docs), but the tool description itself lacks usage context compared to alternatives.

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

list_topicsC

Browse the full corpus index with optional filters.

ParametersJSON Schema
NameRequiredDescriptionDefault
productNo
topic_typeNo

TDQS

C2.3/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure, but it only states it is a browse operation. No information about rate limits, authentication, return format, pagination, or potential side effects is given.

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

Conciseness2/5

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

The description is a single sentence, which is too underspecified to be effective. It lacks structure and fails to convey necessary details efficiently.

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 the lack of output schema, annotations, and meaningful parameter explanations, the description is incomplete. It does not clarify return values, behavior under different filters, or how to interpret results.

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?

Input schema has 0% description coverage and two parameters (product, topic_type) with enums. The description says 'optional filters' but does not explain what the filters mean or how they affect results, failing to compensate for the schema gaps.

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

Purpose3/5

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

The description states 'Browse the full corpus index with optional filters,' which suggests listing or exploring topics but lacks a specific verb-resource combination. It vaguely indicates the tool's purpose but does not distinguish it from siblings like get_topic or search_docs.

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 provided on when to use this tool versus alternatives such as search_docs or get_topic. The description does not mention context, prerequisites, or exclusion conditions.

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

search_docsA

Semantic search across the documentation corpus. Returns ranked topics with relevance scores and excerpts.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results (1–10)
queryYesNatural language search query
productNoFilter by product
versionNoFilter by version e.g. '8.0'

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries full behavioral disclosure. It accurately states the tool performs a search and returns ranked results with scores and excerpts, indicating a read-only operation. It does not disclose potential edge cases like empty results or performance considerations, but the core behavior is clear.

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, well-structured sentence that front-loads the tool's core purpose and output. There is no unnecessary wording, and every part of the sentence adds value.

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?

Given the tool has 4 parameters (all documented in schema) and no output schema, the description sufficiently explains the output format (ranked topics, relevance scores, excerpts). It could elaborate on ranking order or result limits, but the overall context is adequate for a search tool.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are already described in the input schema. The description does not add meaningful context beyond the schema, such as how parameters interact or recommended usage patterns. The phrase 'semantic search' only reinforces the schema's natural language description.

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 states it performs 'semantic search across the documentation corpus' and returns 'ranked topics with relevance scores and excerpts.' It uses specific verbs and resources, and distinguishes from siblings like 'get_topic' and 'list_topics' by specifying search and ranking.

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 usage for finding documentation topics via natural language, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools like 'get_topic' for single topic retrieval.

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

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: evaluating pipelines, checking build status, finding content gaps, retrieving topics, listing topics, and searching docs. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (e.g., evaluate_pipeline, get_build_status, search_docs), making the set predictable and easy to navigate.

Tool Count5/5

With 6 tools, the server is well-scoped for its purpose of documentation knowledge management and pipeline evaluation. The count is neither too sparse nor overwhelming.

Completeness3/5

The server provides read and analysis capabilities (list, get, search, evaluate) but lacks tools for creating, updating, or deleting topics, which are notable gaps for a documentation system.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Bipin-24/knowflow'

If you have feedback or need assistance with the MCP directory API, please join our Discord server