Português | Español

mcp-just-seek-knowledge

MCP (Model Context Protocol) server that stores and searches AI-generated knowledge about software projects, allowing Cursor to access information about project structures, design patterns, best practices, and technical documentation.

📋 About the Project

Objective

Create an MCP server that stores and searches AI-generated knowledge about software projects.

Technology Stack

• Language: Python

• Embedding Framework: LangChain

• Database: PostgreSQL with pgVector

• Protocol: MCP (Model Context Protocol) for Cursor integration

Main Features

1. Ingest: Create new records in the knowledge base

2. Update: Update existing records in the knowledge base

3. Search: Semantic search in the database

4. List Catalog: List all existing service_name in the database (exposed as MCP tool)

5. Delete: Delete records by service_name (available via CLI script, not exposed as MCP tool)

Related MCP server: MCP Memory Server

🛠️ Environment Setup

Complete Setup Process

1. Clone the project or navigate to it (if needed)

cd /home/pereirrd/dev/git/pereirrd/mcp-just-seek-knowledge

2. Create and activate virtual environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/WSL:
source venv/bin/activate

# On Windows:
# venv\Scripts\activate

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Configure environment variables

Create a .env file in the project root (copy from .env.example if it exists, or create manually):

# Example .env
PGVECTOR_URL=postgresql://postgres:postgres@localhost:5433/software_design_knowledge
POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_DB=software_design_knowledge
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
OPENAI_API_KEY=your_openai_api_key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSION=1536

Note: PostgreSQL variables can also be configured in Cursor's mcp.json (see section below).

5. Start PostgreSQL (if using Docker Compose)

docker-compose up -d

This will create PostgreSQL with pgvector automatically on port 5433.

Important: If port 5432 is already in use, docker-compose.yml is configured to automatically use port 5433.

6. Test the MCP server (optional)

python src/mcp_server.py

The server should start without errors and automatically create the software_design_knowledge table if it doesn't exist.

Verify Installation

To verify if dependencies were installed correctly:

pip list | grep -E "langchain|psycopg|openai|python-dotenv"

Or test imports directly:

python -c "from src.database.connection import get_connection_string; from src.mcp.mcp_server import MCPServer; print('✅ Dependencies installed correctly!')"

⚙️ Cursor Configuration

To add this MCP server to Cursor, configure the ~/.cursor/mcp.json file (global configuration) or .cursor/mcp.json in the project root (local configuration).

Example configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-just-seek-knowledge": {
      "command": "python",
      "args": ["/absolute/path/to/project/src/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSION": "1536"
      }
    }
  }
}

Important:

• Use absolute paths in the args field

• Configure all necessary environment variables

• Cursor loads this file automatically on startup

• After adding, restart Cursor to load the MCP server

Note about Cursor

When configuring MCP in Cursor (~/.cursor/mcp.json), Cursor will use the system Python or the one active in PATH. Recommendations:

Option 1: Use global Python (install dependencies globally)

If you prefer to use the system's global Python:

pip install -r requirements.txt

And configure mcp.json with:

{
  "mcpServers": {
    "mcp-just-seek-knowledge": {
      "command": "python",
      "args": ["/absolute/path/to/project/src/mcp_server.py"],
      "env": {
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSION": "1536"
      }
    }
  }
}

Option 2: Use virtual environment Python (recommended)

To use the project's virtual environment, specify the full path to the venv Python in mcp.json:

{
  "mcpServers": {
    "mcp-just-seek-knowledge": {
      "command": "/absolute/path/to/mcp-just-seek-knowledge/venv/bin/python",
      "args": ["/absolute/path/to/mcp-just-seek-knowledge/src/mcp_server.py"],
      "env": {
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSION": "1536"
      }
    }
  }
}

Advantages of Option 2:

• Isolates project dependencies

• Avoids conflicts with other Python projects

• Facilitates version management

Note: The project's .env file will be automatically loaded by the MCP server, so you don't need to repeat PostgreSQL variables in mcp.json (unless you prefer).

🚀 Implementation

Preparation and Structure

Directory Structure

Created src/ structure with organized subdirectories:

• src/database/ - Database management

• src/embeddings/ - Embedding services

• src/services/ - Business services (ingest, update, search)

• src/mcp/ - MCP server and handlers

__init__.py files created in all Python packages.

Dependency Configuration

requirements.txt file created with all necessary dependencies:

• LangChain Framework: langchain, langchain-community, langchain-core, langchain-openai, langchain-postgres

• PostgreSQL: psycopg, pgvector

• OpenAI: openai

• Utilities: python-dotenv

Environment Variables

.env.example file created with all necessary variables:

• PGVECTOR_URL - PostgreSQL connection URL

• POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

• OPENAI_API_KEY, OPENAI_EMBEDDING_MODEL

• EMBEDDING_DIMENSION

.gitignore file configured to exclude .env and Python and IDE files.

Docker and PostgreSQL

docker-compose.yml file created with:

• PostgreSQL service using pgvector/pgvector:pg16 image

• Volume configuration for persistence

• Healthcheck configured

• Ports and environment variables configured

Initialization script init-scripts/01-init-pgvector.sh to automatically create the pgvector extension.

Database Configuration

Database Schema (src/database/schema.py)

Structure of software_design_knowledge table (software project knowledge):

• id - Unique identifier (SERIAL PRIMARY KEY)

• service_name - Service name (VARCHAR(255) NOT NULL UNIQUE)

• content - Knowledge content (TEXT NOT NULL)

• embedding - Embedding vector (vector(1536) NOT NULL)

• metadata - Additional metadata (JSONB)

• created_at - Creation date (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)

• updated_at - Update date (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)

Indexes:

• IVFFlat index for optimized vector search

• Index for service_name for service searches

Triggers:

• Automatic trigger to update updated_at on updates

Connection Management (src/database/connection.py)

Implemented functions:

• get_connection_string() - Gets connection string from environment variables

• create_connection() - Creates PostgreSQL connections

• schema_exists() - Checks if table exists

• create_schema() - Creates complete schema (table, indexes, triggers)

• initialize_database() - Initializes the database

Error handling and logging implemented.

Data Repository (src/database/repository.py)

KnowledgeRepository class implemented using psycopg directly.

Implemented methods:

• insert() - Insert document into database

• update() - Update document by service_name

• upsert() - Insert or update (upsert behavior)

• delete() - Delete document by service_name

• get_by_service_name() - Search document by service_name

• similarity_search() - Semantic search using pgVector (<=> operator)

Features:

• Support for optional filters (similarity threshold, service_name filter)

• Integration with JSONB metadata structure

Embedding Services

EmbeddingService class (src/embeddings/embedding_service.py) using OpenAIEmbeddings from LangChain.

Features:

• Single and batch embedding creation

• Configuration via environment variables (default model: text-embedding-3-small)

• Error handling and logging

Business Services

Four main services implemented:

Ingest Service (src/services/ingest_service.py)

• Adds new knowledge to the database

• Validates service_name and content

• Automatically creates embedding

• Complete error handling

Update Service (src/services/update_service.py)

• Updates existing knowledge (upsert behavior)

• If service_name doesn't exist, creates new record

• If exists, updates existing record

• Automatically updates embedding

Search Service (src/services/search_service.py)

• Semantic search by similarity

• Optional parameters: k (number of results), threshold (minimum similarity), service_name (filter)

• Returns results ordered by relevance

List Catalog Service (src/services/list_catalog_service.py)

• Lists all existing service_name in the database

• Does not use embeddings (repository only)

Common features:

• Integration with EmbeddingService and KnowledgeRepository

• Input validation

• Error handling

• Detailed logging

• Structured returns

🗑️ CLI Scripts

Record Deletion

The project includes a CLI script for record deletion that is not exposed as an MCP tool. This functionality is only available via command line for administrative operations.

Script: src/database/delete_service.py

Functionality:

• Deletes a record from the knowledge base by service_name

• Validates record existence before deletion

• Provides clear feedback on operation result

Usage:

python src/database/delete_service.py <service_name>

Examples:

# Delete a specific service
python src/database/delete_service.py user-service

# The script returns:
# - ✓ "Record deleted successfully" if the record was found and removed
# - ✗ "Record not found" if the service_name doesn't exist
# - ✗ "Error deleting record" in case of operation failure

Features:

• Parameter validation (service_name cannot be empty)

• Error handling with detailed logging

• Appropriate exit codes (0 for success, 1 for failure)

• Clear feedback messages for the user

Note: This functionality is not available as an MCP tool for security and access control reasons. Use only for necessary administrative operations.

📚 pgvector Initialization Script

The init-scripts/01-init-pgvector.sh script is automatically used by PostgreSQL during container initialization.

How it works

1. Volume mapped in docker-compose.yml

The local init-scripts/ directory is mapped to /docker-entrypoint-initdb.d inside the container through volume configuration in docker-compose.yml.

2. PostgreSQL automatic behavior

The official PostgreSQL image (including pgvector/pgvector) automatically executes all files present in /docker-entrypoint-initdb.d when:

• The database is initialized for the first time (when the data volume is empty)

• Files are executed in alphabetical order (hence the 01- prefix)

• Accepts .sql, .sh and other executable files

3. What the script does

The 01-init-pgvector.sh script:

• Executes CREATE EXTENSION IF NOT EXISTS vector; to create the pgvector extension

• Lists installed extensions for verification

• Uses set -e to stop on error

Important

• Scripts in init-scripts/ are only executed on first initialization (when volume is empty)

• If the container has been started before, the script will not be executed again

• To re-execute, it's necessary to remove the volume: docker-compose down -v

⌨️ Cursor Commands (Slash Commands)

This repository includes custom Cursor commands in .cursor/commands/, which help create, update, and list the knowledge base in the MCP mcp-just-seek-knowledge.

Available commands

• /criar_base_conhecimento: analyzes the entire open workspace (all projects/directories), reads documentation (including Swagger/OpenAPI) and creates a unique record for the workspace using mcp-just-seek-knowledge.ingest.

• /atualizar_base_conhecimento: same analysis as the previous command, but updates (upsert) the workspace record using mcp-just-seek-knowledge.update.

• /listar_base_conhecimento: lists existing service_name via mcp-just-seek-knowledge.list_catalog and presents a friendly layout with count, service_name and metadata (enriched via mcp-just-seek-knowledge.search).

How to use

1. Ensure the MCP mcp-just-seek-knowledge is configured in Cursor (~/.cursor/mcp.json or .cursor/mcp.json).

2. Open the project(s) in the Cursor workspace.

3. In Cursor chat, execute a command by typing:

   • /criar_base_conhecimento

   • /atualizar_base_conhecimento

   • /listar_base_conhecimento