Description

Problem

Currently, the Archon MCP server is stateless and requires explicit project_id specification in every tool call. Users must manually track and provide project IDs for each operation (manage_task, manage_document, etc.), which creates friction when working across multiple projects or repositories.

Proposed Solution

Implement automatic project ID detection and management using .archon.json configuration files in repository roots.

Implementation Details

File Structure:

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_name": "Backend API",
  "project_path": "/",
  "github_repo": "https://github.com/user/myApp",
  "created_at": "2024-01-15"
}

Workflow:

1. When Archon MCP operations are initiated, check for .archon.json in the current working directory
2. If file exists, automatically use the stored project_id for all operations
3. If file doesn't exist, prompt to either:
   • Create a new Archon project and generate .archon.json
   • Link to an existing project by selecting from available projects
4. Support traversing up directory tree to find .archon.json (for subdirectories)

Key Benefits:

• Eliminates need to manually specify project_id in every call
• Supports monorepo structures (different .archon.json files in /backend, /frontend, etc.)
• Provides persistent project context across sessions
• Works seamlessly with Claude.ai projects and other coding IDEs
• Maintains flexibility to override with explicit project_id when needed

Acceptance Criteria:

• MCP server checks for .archon.json in current directory
• Automatic project_id injection when file is present
• Project creation flow generates .archon.json automatically
• Support for monorepo with multiple .archon.json files
• Fallback to manual project_id specification when no file exists
• Documentation updated with .archon.json usage examples

Related Discussions:

• [#392](How does the MCP know which Archon project to use? #392) - How does the MCP know which Archon project to use?
• [#377](How to map a projekt (claude project folder) to a Archon projekt? #377) - How to map a projekt to a Archon projekt?