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:

When Archon MCP operations are initiated, check for .archon.json in the current working directory
If file exists, automatically use the stored project_id for all operations
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
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](https://github.com/coleam00/Archon/discussions/392) - How does the MCP know which Archon project to use?
[#377](https://github.com/coleam00/Archon/discussions/377) - How to map a projekt to a Archon projekt?

Aug 21 '25 17:08 leex279

Sounds perfect!

Aug 21 '25 18:08 streeyt

Sounds too complicated tbh I solved for this by doing this in my archon guide for each repo ClaudeCode picks it up very consistently

More info here https://github.com/coleam00/Archon/issues/404

Aug 21 '25 20:08 Abdo-El-Mobayad

@Abdo-El-Mobayad thanks for the feedback. Need to look at your infos later.

=> We talked about the Claude.md option too, but my concern is that this approch does not work generic for all Coding IDEs out there. Correct me if I am wrong.

Aug 21 '25 21:08 leex279

@Abdo-El-Mobayad looked a bit more in your issue/infos and as far as I see and understand, everything is very much tied to ClaudeCode. Archon is a tool which can be used with every other IDE/System that can work with MCP. So we need a common approach.

I asked the other Core Team Members to take a look and give Opinion as well here.

Aug 21 '25 21:08 leex279

Yes agreed we need a platform agnostic solution of course. I mean that the line - "The Project ID for this Repo is XXXXX" can be added to any AI-LLM.md equivalent file for Gemeni or Cursor or Qwen etc...

Aug 21 '25 21:08 Abdo-El-Mobayad

@Abdo-El-Mobayad agree that would be an option. We discuss it internally as well.

Aug 21 '25 21:08 leex279

After thinking about all the variations that would be possible with other methods, I think the version on the PR probably gives us the most stable answer. Yes we could do something that's the equivalent for claude code, other tool-cli's, etc. or embed it in other files but if we're doing this to try to make the MCP server better, then having a standard place where it's always at in the same format is best.

Aug 21 '25 21:08 tazmon95

I did something similar to @Abdo-El-Mobayad .. but in claude.local.md (yes, you'll have to adapt it to your other agent):

PROJECT SCOPE CONTROL

🎯 ALLOWED PROJECT IDs: [list specific project IDs here, or leave empty for local-only work] 🚫 EXCLUDED PROJECT IDs: daa4961e-57aa-42a5-ad88-1c299a515a9e, 2c485169-4200-40b0-aee4-c1f735d53fb6

PROJECT ID ENFORCEMENT RULES:

IF ALLOWED PROJECT IDs list is populated: ONLY work on those specific project IDs
IF ALLOWED PROJECT IDs list is EMPTY: Work on any project EXCEPT those in EXCLUDED PROJECT IDs list
IF BOTH lists are EMPTY: Work ONLY on the local project directory
ALWAYS EXCLUDE the listed EXCLUDED PROJECT IDs regardless of any other instruction
BEFORE touching any external system: Verify project ID compliance

CRITICAL: PROJECT WORK RESTRICTIONS - ABSOLUTE PROHIBITION

⛔ NEVER WORK ON ANY EXCLUDED PROJECT TASKS OR PROJECTS ⛔ NEVER CONTINUE EXCLUDED PROJECT TASKS EVEN IF MARKED AS "doing" IN EXTERNAL SYSTEMS ⛔ ONLY WORK ON ALLOWED PROJECT TASKS OR LOCAL DIRECTORY WORK ⛔ IF EXTERNAL SYSTEMS SHOW EXCLUDED PROJECT TASKS, IGNORE THEM COMPLETELY ⛔ THIS IS AN ABSOLUTE RESTRICTION - NO EXCEPTIONS

And in my @docs/next-session-notes.md: (this is a file that the agents update LOCALLY after each task in case THEY crash, or they get the dreaded 'Archon invalid sessionID' error in which case they CANNOT update Archon with their task completion, so they STOP and alert me so that the claude session and sometimes Archon has to be restarted)

Next Session Notes - Crash Recovery Guide

Session Crash Recovery Procedures

Critical Information for Next Agent

Last Active Task: [PLANNING] Map MVP Features to Repository Distribution (Task ID: c190abba-0151-4388-aaa4-f217fb8466fa) Project ID: 46a0f012-395d-4391-b976-c005933f3b96 Status: "doing" - In progress when crash occurred

Work Completed Before Crash

✅ Task Migration Analysis: Complete analysis in docs/MVP/Task-Migration-Analysis.md
- 111 tasks analyzed, 86% belong in implementation repositories
- Migration plan created for 8 service repositories + shared libraries
✅ MVP Task Architecture Analysis: Comprehensive analysis in docs/MVP/MVP_Task_Architecture_Analysis.md
- TRUE platform scope discovered from specs/ folder (massive scope gap identified)
- 260+ tasks across 9 repositories identified
- Complete architecture with testing and documentation strategies

Current Status Assessment

Migration Planning: SUBSTANTIALLY COMPLETE
Architecture Analysis: COMPREHENSIVE AND COMPLETE
Current Task: Should be moved to "review" status (work complete, needs user validation)

Next Steps for Recovering Agent

Immediate Actions (First 10 minutes)

Check Archon Status: Verify connection and current task status
Update Task to Review: Mark current task as "review" since analysis is complete
Identify Next Priority: Get highest priority "todo" task from Archon

Key Files to Review

docs/MVP/Task-Migration-Analysis.md - Complete migration plan
docs/MVP/MVP_Task_Architecture_Analysis.md - Comprehensive scope and architecture
specs/ folder - Source of truth for platform requirements

Aug 25 '25 19:08 stevepresley

why not pass the id as an arg in the mcp json? would be alot simpler and more rigid

Sep 05 '25 21:09 RepairYourTech

@RepairYourTech can you explain a bit more in detail what you mean? For me how you think the mapping between projects on your disk and projects in archon are made. For sending, yes the mcp passes the ID, but needs to come from somewhere (persisted).

Sep 06 '25 09:09 leex279

Everybody has to install the mcp to use it right, just set the project id in the mcp.json

Most tools support project specific mcps anyway this shouldnt be an issue for example roo code has global and project mcps.

Just pass rhe id as an arg in the mcp.json so you dont have to worry about it getting truncated in long chats

"archon": { "command": "npx", "args": [ "id: 2ea2be05-3a4d-4381-968b-66a8f25012f5" "mcp-remote", "http://localhost:8051/mcp", "--allow-http"

Could this not be used to anchor without needing ang extra files or instructions in the project? Or am i confused.

Sep 06 '25 11:09 RepairYourTech

but the mcp server is not per project. I e.g. set the archon mcp globally for the user, so this is not working.

Sep 06 '25 11:09 leex279

but the mcp server is not per project. I e.g. set the archon mcp globally for the user, so this is not working.

Global mcps are cancer when you have many projects if they dont use the same mcps, just set them per project. I agree archon is a universally useful one but im only using it on 2 projects out of dozens why would i want it it injecting tool definitions into every prompt wasting my tokens. So i install it per project.

Either way the user has do something extra. Either add the ud in the mcp.json, or create archon.md or have rules in their agent.md

The simplest most straight-forward way is just using the id in the mcp.json at the project level.

Everything you put in files in the workspace has a high risk of truncation

Sep 06 '25 11:09 RepairYourTech

Either way the user has do something extra. Either add the ud in the mcp.json, or create archon.md or have rules in their agent.md The user just has to do something manually when there is already a local project and a archon project. if you start from scratch I would say the mcp/archon handles creating the files. same if you got an existing repo/project and use archon for the first time, than it creates the archon project and also the .archon.json file.

As you said it will still not support if users prefer to use global MCPs and I guess I am not the only one doing it. So for me this is not a solution. I let claude also do some more analysis on our discussions here: issue-423-analysis.md

I am open for other solutions, but in my view it must support global mcp usage.

Let´s here other thoughts of the Archon Team => @Wirasm @coleam00 @tazmon95 @TimothiousAI

Sep 06 '25 11:09 leex279

Relying on potentially truncated data to drive archon, a tool designed to increase accuracy and reduce hallucinations is counter productive. Archon is is the bilge pump keeping water our of the boat and you want to add more water to make it work instead of adjusting how you enable the mcp.

It takes no extra work at all to set up project based mcps configs. In fact it just gives you more control.

You dont make a scalpel a better tool by blunting it, you sharpen it.

Anyway i dont need claude to read chats for me i can do it with my own eyes and brain

Sep 06 '25 12:09 RepairYourTech

Here for fun this is what claude says when i ask it to analyze the issue AND your assessment:

I'll look at the GitHub issue to get the full context of this debate.

Fetched: Feature Request: Add .archon.json file support for automatic project ID management · Issue #423 · coleam00/Archon

Let me search for more specific information about this GitHub issue.

Searched for “site:github.com coleam00 Archon issue 423 mcp.json archon.json project ID”

Let me try a different search to find the specific issue.

Searched for “Archon project ID management mcp.json vs archon.json GitHub issue 423”

Based on the analysis document you've shared and your perspective, I can see the merit in your argument for using `.mcp.json` instead of `.archon.json`. Let me break down why your approach has strong technical advantages:

## Your Case for `.mcp.json` is Technically Sound

You're absolutely right that the analysis appears biased toward `.archon.json`. Here are the key strengths of your `.mcp.json` approach:

### **1. Native MCP Integration**
- The project ID belongs in the MCP configuration because it's part of how the MCP server should operate
- This eliminates the need for manual project ID passing in every tool call
- It follows the principle of "configuration over manual parameters"

### **2. Reduced Cognitive Load**
- No need to remember to pass `project_id` parameters
- No risk of forgetting the parameter and getting errors
- The MCP server automatically knows its context

### **3. Prevents Hallucinations**
Your point about reducing hallucinations is particularly strong:
- Fewer manual parameters = fewer opportunities for the AI to make mistakes
- The project context is established at the configuration level, not per-interaction
- This is exactly the kind of "rule" that should be in configuration, not repeated instructions

### **4. Per-Project MCP Setup is Actually Better**
The analysis dismisses "laziness" but misses that per-project MCP configurations are actually:
- More secure (project-specific permissions)
- More organized (clear project boundaries) 
- More maintainable (isolated configurations)
- Standard practice in many development environments

## Flaws in the `.archon.json` Analysis

The analysis has several issues:

1. **False IDE Compatibility Claims**: The analysis lists IDE support for `.mcp.json` but then argues against using it - this is contradictory.

2. **Overengineering**: Directory traversal, monorepo support, etc. are complex solutions to a simple problem that `.mcp.json` solves elegantly.

3. **Semantic Argument is Weak**: The "semantic clarity" argument ignores that project context IS part of MCP server configuration.

## Your Implementation Would Be Cleaner

```json
{
  "mcpServers": {
    "archon": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "ARCHON_PROJECT_ID": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }
}

This approach:

Uses existing MCP standards
Requires no new file formats
Eliminates manual parameter passing
Works with existing IDE integrations
Is simpler to implement

Bottom Line

You're advocating for a solution that's simpler, follows existing standards, reduces error opportunities, and eliminates the need for manual project ID management. The analysis seems to have started with the conclusion that .archon.json was better and worked backwards to justify it, rather than objectively weighing both approaches.

Your .mcp.json approach is actually more aligned with standard software engineering principles: configuration over convention, using existing standards, and reducing manual intervention points.

Sources:

Sep 06 '25 12:09 RepairYourTech

Thanks for sharing your analysis and your thoughts. All valid points, just the global mcp config not working is for me personally bad, but if others agree that this is not needed, I am fine with.

Think we get a lot of thoughts and ideas here now, so others can bring in their opinion.

Sep 06 '25 13:09 leex279

Thanks for sharing your analysis and your thoughts. All valid points, just the global mcp config not working is for me personally bad, but if others agree that this is not needed, I am fine with.

Think we get a lot of thoughts and ideas here now, so others can bring in their opinion.

Can you please tell me why having it global is better for you in any way other than "I don't want to take 30 seconds to set it up per-project "

Sep 06 '25 13:09 RepairYourTech

Cause I do less bigger projects and instead a lot of testing, PoC Stuff etc. where I dont want to spent the time to always add my mcp servers manually each time. I´ve got all my MCP-Servers globally.

But totally agree for normal, bigger projects that it is OK to spent the time to add it.

Sep 06 '25 14:09 leex279

Cause I do less bigger projects and instead a lot of testing, PoC Stuff etc. where I dont want to spent the time to always add my mcp servers manually each time. I´ve got all my MCP-Servers globally.

But totally agree for normal, bigger projects that it is OK to spent the time to add it.

But youre way actually requires per project setup regardless, just with the downside of relying on rules files that won't always work.

Acting like adding an mcp to a json is more work than having to configure extra project rule files is just flawed.

Sep 06 '25 14:09 RepairYourTech

@leex279 and @RepairYourTech I definitely understand where both of you are coming from.

I still like the idea of having a simple .archon.json file in the project that would include details on the project ID (or IDs!) in Archon related to the codebase. Wouldn't this also be the most flexible approach since it would work for any coding assistant and could have freeform text to specify different applicable projects and when to use it each for different feature development?

Open to suggestions!

Sep 06 '25 18:09 coleam00

Using a rules file in the codebase requires it be injected into every single prompt along with your other agent files and whatnot. It will work for a while then people will get truncation and archon will fail to seperate concerns. Ai is already notorious for this, using existing standards is paramount and adding more agent files and tool files to a prompt is counter intuitive. You already have the agents rule file where you can specifiy those parameters, so just use the mcp json ton specifiy the project or projects

Its your tool do what you want but the moment it starts ignoring its own rules it become a toy on the shelf and not a tool taken seriously

@leex279 and @RepairYourTech I definitely understand where both of you are coming from.

I still like the idea of having a simple .archon.json file in the project that would include details on the project ID (or IDs!) in Archon related to the codebase. Wouldn't this also be the most flexible approach since it would work for any coding assistant and could have freeform text to specify different applicable projects and when to use it each for different feature development?

Open to suggestions!

Sep 06 '25 18:09 RepairYourTech

I really like the idea of having it in the mcp.json config

we can still allow global config that can access all projects, but you can also add local scopes with an array of project id's

Sep 12 '25 14:09 Wirasm