# Agent Guide - LightRAG MCP Server
This guide provides instructions for agentic coding agents working in this repository. Adhere to these standards to ensure consistency and reliability.
## 1. Development Environment & Commands
### Setup
- **Environment**: Use a Python virtual environment (venv).
- **Dependencies**: `pip install -r requirements.txt`
- **Environment Variables**: Copy `.env.example` to `.env` and configure accordingly.
### Build & Run
- **Start MCP Server**: `python lightrag_mcp.py`
- Default port: 8000 (configurable via `mcp.settings.port`).
- Transport: FastMCP (HTTP/SSE).
### Testing & Linting
- **Linting**: Use `ruff check .` (if installed) or follow PEP 8.
- **Testing**:
- Currently, manual testing is performed using the snippet in `README.md`.
- When implementing tests, use `pytest`.
- Run a single test: `pytest tests/test_filename.py::test_function_name`
- **Verification**: Ensure the MCP tool is visible via `mcp.list_tools()` if testing via the Python SDK.
---
## 2. Code Style & Conventions
### Python Standards
- **Version**: Python 3.10+
- **Naming**:
- Variables/Functions: `snake_case`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- **Typing**: Use Type Hints for all function signatures. MCP tool inputs/outputs **must** be typed.
- **Docstrings**: All `@mcp.tool()` functions must have detailed docstrings. The docstring is used by the LLM to understand when and how to call the tool.
### Imports
- Place all imports at the top of the file.
- Group imports: Standard library, third-party, then local modules.
### Error Handling
- Use `try...except` blocks for all network operations (using `httpx`).
- Log exceptions using `logging.exception("Contextual message")`.
- Return descriptive error strings from tools instead of allowing them to crash.
### Configuration
- **Environment Variables**: Access via `os.environ.get()` with sensible defaults.
- **System Prompts**:
1. Check `LIGHTRAG_SYSTEM_PROMPT` (env var).
2. Check `LIGHTRAG_SYSTEM_PROMPT_FILE` (file path).
3. Default to `./prompts/light_rag_system.txt`.
---
## 3. Project Structure
- `lightrag_mcp.py`: Main entry point. Contains server initialization and tool definitions.
- `prompts/`: Directory for system prompt templates.
- `.env`: Local configuration (git-ignored).
- `requirements.txt`: Project dependencies.
---
## 4. Security
- Never commit `.env` files or hardcode API keys.
- Be cautious when adding `allowed_hosts` to transport security to prevent unauthorized access.
