🐛 Critical Bug: list_projects Returns Full Project Content (180k+ Tokens)

📋 Bug Description

The mcp__archon__list_projects function returns complete project content instead of lightweight metadata, causing massive token consumption that makes the Archon MCP server practically unusable for project management.

💥 Impact

• Token Consumption: 180,000+ tokens for listing just 3 projects
• Expected: ~500-1000 tokens for basic project listing
• Cost Impact: 360x token usage increase (from $0.01 to $3.60+ per list operation)
• Usability: Makes basic project navigation financially prohibitive

🔍 Technical Details

API Call

// MCP function call
mcp__archon__list_projects()

// Expected lightweight response (~500 tokens)
// Actual response: 180,000+ tokens with full project content

Current Response Structure (Problematic)

{
  "success": true,
  "projects": [
    {
      "id": "project-uuid-1",
      "title": "Project Name",
      "description": "Project description...",
      "docs": [
        {
          "id": "doc-uuid",
          "content": { /* MASSIVE NESTED OBJECTS */ },
          "tags": [...],
          "author": "...",
          // Full document content included
        }
        // ... potentially dozens of documents
      ],
      "features": {
        // HUGE nested objects with all feature details
        "feature1": { /* complex nested data */ },
        "feature2": { /* complex nested data */ }
      },
      "data": {
        // MASSIVE application data objects
        /* All project data included */
      },
      "technical_sources": [...], // Large arrays
      "business_sources": [...], // Large arrays
      // ... all project content included
    }
    // ... repeated for each project
  ]
}

Expected Lightweight Response

{
  "success": true,
  "projects": [
    {
      "id": "project-uuid-1", 
      "title": "Project Name",
      "description": "Brief description",
      "created_at": "2025-08-26T06:32:49.357594+00:00",
      "updated_at": "2025-08-26T07:14:57.399902+00:00",
      "github_repo": "https://github.com/user/repo",
      "pinned": false,
      "stats": {
        "docs_count": 5,
        "tasks_count": 12,
        "features_count": 3
      }
    }
  ],
  "total_count": 3
}

🔄 Steps to Reproduce

1. Setup: Create 2-3 Archon projects via MCP
2. Add Content: Create several documents and tasks in each project
3. Trigger Bug: Call mcp__archon__list_projects()
4. Observe: Response contains full project content (180k+ tokens)
5. Verify: Check token consumption in Claude Code usage

Environment

• MCP Server: Archon (latest version)
• Client: Claude Code CLI
• API Model: Claude Sonnet 4
• Date: August 2025

🎯 Expected Behavior

list_projects should return only essential project metadata:

• Basic info: id, title, description, timestamps
• Repository info: github_repo, pinned status
• Summary stats: counts of docs, tasks, features
• Total response: 500-1000 tokens maximum

💡 Proposed Solutions

Option 1: Lightweight Default Response

// Default call returns lightweight data
mcp__archon__list_projects()

// Optional parameter for full content when needed
mcp__archon__list_projects({ include_content: true })

Option 2: Separate Endpoints

// Lightweight listing (default)
mcp__archon__list_projects() 

// Full project details when needed
mcp__archon__get_project(project_id: "uuid")

Option 3: Field Selection

// Specify which fields to include
mcp__archon__list_projects({ 
  fields: ["id", "title", "description", "created_at"] 
})

🚨 Business Impact

• Development Workflow: Blocks basic project navigation
• Financial: Causes unexpected API credit depletion
• User Experience: Makes Archon impractical for real-world use
• Scalability: Problem worsens as projects grow in content

📈 Severity Assessment

CRITICAL - This is a blocking issue that makes the Archon MCP server unusable for any project with meaningful content due to excessive token consumption.

🔧 Additional Context

This bug was discovered during active development when a simple project listing operation consumed 180k tokens in 2 API calls, unexpectedly depleting API credits. The current behavior violates standard REST API practices where listing endpoints should return lightweight summaries, not full object graphs.

The issue affects all users of the Archon MCP server and fundamentally breaks the expected cost model for project management operations.