knowledge-mcp AGENTS.md

AGENTS.md - Agentic Coding Guidelines for knowledge-mcp

This file provides guidelines for AI agents operating in this repository.

Project Overview

• Project: knowledge-mcp - A MCP server bridging specialized knowledge domains and AI assistants
• Language: Python 3.12
• Build System: hatchling
• Dependency Manager: uv

Ignore Patterns

• data/
• archive/
• tmp/

Build, Lint, and Test Commands

Running Tests

# Run all tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_config.py

# Run a single test
uv run pytest tests/test_config.py::test_successful_config_loading

# Run tests with verbose output
uv run pytest -v

# Run tests matching a pattern
uv run pytest -k "test_config"

Development Commands

# Install in development mode
uv sync --group dev && uv pip install -e .

# Run the MCP server with uvx
uvx knowledge-mcp --config ./kbs/config.yaml mcp

# Run the interactive shell
uvx knowledge-mcp --config ./kbs/config.yaml shell

# Run the CLI directly
uv run knowledge-mcp

# Clean build artifacts
rm -rf build/ dist/ *.egg-info/
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

Note: The Makefile provides convenient shortcuts (make dev-install, make insp, make shell, make main, make test, make clean) as an alternative to these uv commands.

Using uv

# Add a dependency
uv add <package>

# Remove a dependency
uv remove <package>

# Sync dependencies
uv sync

# Use uv pip only if really necessary
uv pip install <package>

Code Style Guidelines

General Principles

• Use Python 3.12 features and syntax
• Follow PEP 8 style guide (Ruff is the primary linter/formatter)
• Use explicit code that clearly communicates intent over implicit, overly concise code
• Keep the Zen of Python in mind when making design decisions
• Do not over-engineer solutions. Strive for simplicity and maintainability while still being efficient.
• Favor modularity, but avoid over-modularization.