Skip to main content
Glama
gilanggsb

knowledge-mcp

by gilanggsb
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Knowledge MCP Server

A vendor-neutral Knowledge MCP server for Codex, OpenCode, Claude Code, Gemini CLI, and other MCP-compatible clients.

Overview

This server provides a stable MCP interface for knowledge retrieval across repositories. The MCP contract remains stable while storage, search, embedding, indexing, and transport implementations can be replaced independently.

Related MCP server: mcp-documentacao

Features

  • Stable MCP Contract v1: knowledge_search, knowledge_get, knowledge_list

  • Vendor-Neutral Architecture: Ports and adapters pattern

  • Hybrid Retrieval: Lexical (SQLite FTS) + Optional Semantic (Qdrant)

  • Docker Support: Multi-stage BuildKit builds, multi-platform (amd64/arm64)

Quick Start

Prerequisites

  • Python 3.12+

  • uv package manager

  • Docker (optional, for containerized deployment)

Local Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run the server (stdio mode)
uv run python -m knowledge_mcp

# Run with HTTP transport
TRANSPORT=http uv run python -m knowledge_mcp

Docker Deployment

# Build image
make docker-build

# Start container
make docker-up

# View logs
make docker-logs

# Stop container
make docker-down

Project Structure

knowledge-mcp/
├── src/knowledge_mcp/     # Main package
│   ├── __init__.py
│   ├── __main__.py        # CLI entrypoint
│   └── server.py          # Server implementation
├── tests/                 # Test suite
├── docs/                  # Documentation
│   ├── decisions/         # Architecture Decision Records
│   └── contracts/         # MCP contract definitions
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── pyproject.toml

Architecture

The server follows the ports and adapters (hexagonal) architecture:

MCP / CLI / watcher entrypoints
               |
               v
       application services
               |
               v
         domain and ports
               ^
               |
  infrastructure adapters

Domain and application packages never import infrastructure, MCP SDK, or provider-specific types.

MCP Contract v1

Tools

Tool

Description

knowledge_search

Search knowledge with scope, filters, and limits

knowledge_get

Retrieve exact document or section by ID

knowledge_list

List documents with prefix and depth filtering

Resources

URI

Description

knowledge://system/status

Server status and health

knowledge://documents/{document_id}

Document content resource

Knowledge Routing

Mode

Use Case

LOCAL_ONLY

Explicit target, one repository, low architectural risk

MCP_REPO

Ambiguous location, multiple layers

MCP_GLOBAL

Cross-repository, architecture, security

Configuration

See .env.example for available configuration options.

Key Settings

  • TRANSPORT: stdio, http, or sse

  • KNOWLEDGE_ROOT: Path to knowledge sources

  • LEXICAL_PROVIDER: sqlite_fts (default), or disabled

  • SEMANTIC_PROVIDER: disabled (Phase 8: qdrant)

Development

Quality Gates

# Format check
uv run ruff format --check .

# Lint check
uv run ruff check .

# Type check
uv run pyright

# All checks
make test-ci

Phase Implementation

This project follows a phased implementation approach. See the implementation plan for details.

License

MIT

Available Tools

3 tools
knowledge_getA

Get the full content of a specific knowledge document by its document ID. Can retrieve specific sections.

ParametersJSON Schema
NameRequiredDescriptionDefault
sectionNoOptional section heading to retrieve
max_charsNoMaximum characters to return
document_idYesThe document ID to retrieve

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It claims to retrieve 'full content', but the input schema includes a max_chars parameter that can truncate output, creating a potential contradiction between what the description says and the tool's actual behavior. The description also does not mention permissions, errors, or the safety of the read operation.

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 sentences, front-loaded with the main purpose, and contains zero unnecessary words. Every sentence contributes meaning.

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?

While the tool is simple and the schema covers parameters, there is no output schema. The description only says 'full content' without explaining the return format or whether truncation can occur. It also does not clarify how this tool relates to siblings, leaving some contextual gaps for an agent.

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 description coverage is 100%, so the baseline is 3. The description adds context for document_id by mentioning 'by its document ID' and for section with 'specific sections', but it does not explain max_chars beyond what the schema already provides.

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 retrieves the full content of a knowledge document by ID, using the specific verb 'get' and the resource. It also mentions the ability to retrieve specific sections, which distinguishes it from sibling tools like knowledge_search and knowledge_list.

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 when you have a document ID and need its content, but it does not explicitly state when to use this tool instead of knowledge_search or knowledge_list. There are no explicit exclusions or alternatives mentioned, so guidance is only implied.

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

knowledge_listB

List knowledge documents with optional filtering by scope and prefix.

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNoTraversal depth
limitNoMaximum results
scopeYesList scope
prefixNoLogical knowledge prefix filter
repositoryNoRepository ID (required for repository scope)

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, the description must carry behavioral transparency, but it only states the literal action without disclosing any additional behavioral traits (e.g., read-only guarantee, pagination, auth requirements, potential cost). Listing is implicitly read-only, but the description adds no value beyond the action itself.

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 sentence that is front-loaded with the primary action and quickly mentions optional filtering. It is concise with no wasted words.

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?

Without an output schema, the description should explain return values, but it doesn't. It also does not mention dependencies like repository being required for repository scope, though the schema covers that. The description is too minimal to be fully contextual for a 5-parameter tool with no output schema.

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 description coverage is 100%, so the baseline is 3. The description mentions 'scope and prefix' as filters, but this doesn't add meaning beyond what the schema already describes for these parameters. It doesn't enrich the parameter understanding.

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 says 'List knowledge documents', which is a specific verb and resource. The mention of optional filtering by scope and prefix distinguishes it from sibling tools like knowledge_search (which likely searches) and knowledge_get (which likely gets a single document).

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 by stating it lists documents with optional filtering, but it does not explicitly compare to alternatives or state when not to use it. It lacks clear context on when to choose this over knowledge_search or knowledge_get, though the verb 'list' gives a hint.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedknowledge_get
    • First observedknowledge_list
    • First observedknowledge_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: knowledge_search for query-based relevance, knowledge_get for retrieving by ID, and knowledge_list for enumerating with filters. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent pattern: knowledge_ + verb (search, get, list). The naming is uniform and predictable, with no mixed conventions.

Tool Count5/5

Three tools is a well-scoped count for a read-focused knowledge server. Each tool covers a distinct core operation (search, retrieve, list) without unnecessary bloat.

Completeness2/5

The server is entirely read-only, offering no operations to create, update, or delete knowledge documents. For a domain implied as 'knowledge management', this is a significant gap that would prevent agents from writing to the knowledge base.

Maintenance

ActivityMaintained
ResponsivenessNo issues

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

  • mcp-docs

    pgupta1795
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for documentation search that automatically indexes web documentation sites and provides semantic, full-text, or hybrid search capabilities.
    14
    MIT

  • mcp-local-rag

    xiuxiansk
    A
    license
    A
    quality
    C
    maintenance
    MCP server that enables local hybrid semantic and keyword search over private PDF, DOCX, Markdown, and text documents without sending data to embedding APIs.
    9
    4,707
    MIT

  • MCPedia

    asepharyana
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for a content-first knowledge base, enabling AI agents to search (full-text, semantic, hybrid) and retrieve Markdown documents, list content, and find related docs.
    18
    MIT

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/gilanggsb/knowledge-mcp'

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