python/src/mcp_server/mcp_instructions.md

Archon MCP Server Instructions

🚨 CRITICAL RULES (ALWAYS FOLLOW)

1. Task Management: ALWAYS use Archon MCP tools for task management.

   • Combine with your local TODO tools for granular tracking

2. Research First: Before implementing, use rag_search_knowledge_base and rag_search_code_examples

3. Task-Driven Development: Never code without checking current tasks first

🎯 Targeted Documentation Search

When searching specific documentation (very common!):

1. Get available sources: rag_get_available_sources() - Returns list with id, title, url
2. Find source ID: Match user's request to source title (e.g., "PydanticAI docs" -> find ID)
3. Filter search: rag_search_knowledge_base(query="...", source_id="src_xxx", match_count=5)

Examples:

• User: "Search the Supabase docs for vector functions"

  1. Call rag_get_available_sources()
  2. Find Supabase source ID from results (e.g., "src_abc123")
  3. Call rag_search_knowledge_base(query="vector functions", source_id="src_abc123")

• User: "Find authentication examples in the MCP documentation"

  1. Call rag_get_available_sources()
  2. Find MCP docs source ID
  3. Call rag_search_code_examples(query="authentication", source_id="src_def456")

IMPORTANT: Always use source_id (not URLs or domain names) for filtering!

📋 Core Workflow

Task Management Cycle

1. Get current task: list_tasks(task_id="...")
2. Search/List tasks: list_tasks(query="auth", filter_by="status", filter_value="todo")
3. Mark as doing: manage_task("update", task_id="...", status="doing")
4. Research phase:
   • rag_search_knowledge_base(query="...", match_count=5)
   • rag_search_code_examples(query="...", match_count=3)
5. Implementation: Code based on research findings
6. Mark for review: manage_task("update", task_id="...", status="review")
7. Get next task: list_tasks(filter_by="status", filter_value="todo")

Consolidated Task Tools (Optimized ~2 tools from 5)

• list_tasks(query=None, task_id=None, filter_by=None, filter_value=None, per_page=10)
  • list + search + get in one tool
  • Search with keyword query parameter (optional)
  • task_id parameter for getting single task (full details)
  • Filter by status, project, or assignee
  • Optimized: Returns truncated descriptions and array counts (lists only)
  • Default: 10 items per page (was 50)
• manage_task(action, task_id=None, project_id=None, ...)
  • Consolidated: create + update + delete in one tool
  • action: "create" | "update" | "delete"
  • Examples:
    • manage_task("create", project_id="p-1", title="Fix auth")
    • manage_task("update", task_id="t-1", status="doing")
    • manage_task("delete", task_id="t-1")

🏗️ Project Management

Project Tools

• list_projects(project_id=None, query=None, page=1, per_page=10)
  • List all projects, search by query, or get specific project by ID
• manage_project(action, project_id=None, title=None, description=None, github_repo=None)
  • Actions: "create", "update", "delete"

Document Tools

• list_documents(project_id, document_id=None, query=None, document_type=None, page=1, per_page=10)
  • List project documents, search, filter by type, or get specific document
• manage_document(action, project_id, document_id=None, title=None, document_type=None, content=None, ...)
  • Actions: "create", "update", "delete"

🔍 Research Patterns

CRITICAL: Keep Queries Short and Focused!

Vector search works best with 2-5 keywords, NOT long sentences or keyword dumps.

✅ GOOD Queries (concise, focused):

• rag_search_knowledge_base(query="vector search pgvector")
• rag_search_code_examples(query="React useState")
• rag_search_knowledge_base(query="authentication JWT")
• rag_search_code_examples(query="FastAPI middleware")

❌ BAD Queries (too long, unfocused):

• rag_search_knowledge_base(query="how to implement vector search with pgvector in PostgreSQL for semantic similarity matching with OpenAI embeddings")
• rag_search_code_examples(query="React hooks useState useEffect useContext useReducer useMemo useCallback")

Query Construction Tips:

• Extract 2-5 most important keywords from the user's request
• Focus on technical terms and specific technologies
• Omit filler words like "how to", "implement", "create", "example"
• For multi-concept searches, do multiple focused queries instead of one broad query

📊 Task Status Flow

todo → doing → review → done

• Only ONE task in 'doing' status at a time
• Use 'review' for completed work awaiting validation
• Mark tasks 'done' only after verification

📝 Task Granularity Guidelines

Project Scope Determines Task Granularity

For Feature-Specific Projects (project = single feature): Create granular implementation tasks:

• "Set up development environment"
• "Install required dependencies"
• "Create database schema"
• "Implement API endpoints"
• "Add frontend components"
• "Write unit tests"
• "Add integration tests"
• "Update documentation"

For Codebase-Wide Projects (project = entire application): Create feature-level tasks:

• "Implement user authentication feature"
• "Add payment processing system"
• "Create admin dashboard"