qmcp: Instructions file for Codex

AGENTS.md - Instructions for AI Agents

This file contains instructions for AI agents working on or with this project.

Project Overview

• Project Name: qmcp (QDrant MCP Server)
• Purpose: Semantic search server for code and documentation using Qdrant vector database
• Language: Python 3.11+
• Framework: FastMCP (MCP Python SDK)

Key Commands

Quick Start

# Install dependencies
make install

# Install as MCP server for OpenCode
make mcp-install

# Run tests
make test

# Lint code
make lint

Development

# Run in development mode (with MCP inspector)
make mcp-dev

# Run with coverage
make test-cov

# Format code
make format

Architecture

See ARCHITECTURE.md for detailed system architecture.

File Structure

qmcp/
├── src/
│   ├── qmcp/
│   │   ├── server.py      # FastMCP server, tools definition
│   │   ├── client.py     # Qdrant client wrapper
│   │   ├── config.py     # Pydantic settings
│   │   ├── indexer.py    # Code indexing logic
│   │   ├── watcher.py    # File system watcher
│   │   ├── cleanup.py    # Stale vector cleanup
│   │   ├── logging_config.py  # Logging configuration
│   │   ├── parser/       # Multi-language parsers
│   │   │   ├── base.py   # Parser interface
│   │   │   ├── python.py # AST parser
│   │   │   └── multi.py  # tree-sitter parsers
│   │   └── models.py     # Pydantic models
│   └── main.py           # Entry point
├── tests/
│   ├── test_server.py
│   ├── test_indexer.py
│   ├── test_parser.py
│   ├── test_watcher.py
│   └── test_cleanup.py
├── chart/                # Helm chart (optional, for production)
├── Makefile
└── pyproject.toml

Adding New Features

Adding a New Tool

1. Add tool function to src/qmcp/server.py:

   @mcp.tool()
   async def my_new_tool(param: str = Field(...)) -> dict:
       """Tool description for LLM."""
       # Implementation
       return result
   

2. Add tests to tests/test_server.py