Skip to main content
Glama
knowledge-mcp

knowledge-mcp

by gilanggsb

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.

Inputs: document_id (required), section, max_chars.

knowledge_listB

List knowledge documents with optional filtering by scope and prefix.

Inputs: scope (required), depth, limit, prefix, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    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.

    Related MCP Connectors

    Related MCP Servers

    • 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.
      7 npm
      MIT
    • A
      license
      A
      quality
      D
      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
      MIT
    • F
      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.
      -