feat(mcp): add --project flag and ARCHCORE_PROJECT_ROOT env override

Author: ivklgn

.archcore/cli/mcp-token-optimization.idea.md

@@ -7,7 +7,23 @@ status: draft
 
 Reduce token consumption of the MCP server by deduplicating tool descriptions, trimming redundant response fields, and consolidating disambiguation rules — without sacrificing document classification accuracy.
 
-Current baseline: **~5,600 tokens/session** fixed overhead (system instructions ~2,900 + tool schemas ~2,100 + session context ~600). Realistic savings: **800–1,300 tokens/session (15–23%)**.
+Original baseline: **~5,600 tokens/session** fixed overhead (system instructions ~2,900 + tool schemas ~2,100 + session context ~600). Realistic savings: **800–1,300 tokens/session (15–23%)**.
+
+## Status
+
+**Partially shipped** in commit `05d1af3 fix: safe token optimizations in MCP tools` (2026-05-12). The "safe" subset — changes that do not alter the response contract or risk type-selection accuracy — has landed. The riskier items (response-shape changes and full system-prompt consolidation) remain open and are tracked below.
+
+### Shipped (safe)
+
+- **Compressed `create_document` description** (partial Item 1). The 18 document types are still enumerated in the tool description, but each entry is now one or two lines instead of a full multi-line section list. Section detail is delegated to the auto-generated template. The `tags` and `content` parameter descriptions were also tightened, with longer reference text pushed to server instructions. Net effect: roughly half the tokens of the original create_document schema, without removing type guidance.
+- **`nearby_documents` cap** (Item 5). `populateNearbyDocuments` in `internal/mcp/tools/create_document.go` now sorts results alphabetically and caps at `maxNearbyDocuments = 5`. Bounds the response size in large directories.
+
+### Not shipped (deferred)
+
+- **Item 1 (full)** — Removing the type list from `create_document` entirely and pointing to system instructions. The compressed version was chosen instead because tool-schema-weighted models still benefit from in-schema type names. Full deduplication remains a candidate if A/B testing shows the compressed list is also expendable.
+- **Item 2 — Remove `filename` + `slug` from `list_documents` response.** Both fields are still in `LocalDocument` (`internal/mcp/tools/common.go`). Mechanically derivable from `path`. ~430 tokens / 50 docs.
+- **Item 3 — Strip frontmatter from `content` in `get_document` response.** Still returned verbatim. Contract change — needs a migration plan (or a `raw` opt-in parameter) before shipping. ~10–14 tokens/call.
+- **Item 4 — Consolidate requirements tracks + layers + type selection in `mcpServerInstructions`.** `internal/mcp/server.go` was not touched in `05d1af3`. ~150–200 tokens.
 
 ## Value
 
@@ -16,7 +32,7 @@ Current baseline: **~5,600 tokens/session** fixed overhead (system instructions
 - More headroom in context window for actual user work
 - No degradation in document quality or type selection accuracy
 
-## Current Token Budget
+## Current Token Budget (pre-`05d1af3` baseline)
 
 | Component | Tokens | % |
 |---|---|---|
@@ -26,6 +42,8 @@ Current baseline: **~5,600 tokens/session** fixed overhead (system instructions
 | Session-start context (doc list + relations) | ~600 | 10% |
 | **Total baseline** | **~5,600** | **100%** |
 
+Post-`05d1af3` figures have not been re-measured. Re-baseline before deciding whether the remaining items are worth pursuing.
+
 ### System Prompt Breakdown
 
 | Section | Tokens | % of instructions |
@@ -47,24 +65,24 @@ Minimal prompts yield 25–40% error rate (wrong type, missing sections). Curren
 
 ## Possible Implementation
 
-### 1. Deduplicate `create_document` description (~500–700 tokens saved)
-The tool description re-lists all 18 types with required sections (~700 tokens) that already exist in system instructions. Replace with a reference: "See system instructions for required sections per type."
+### 1. Deduplicate `create_document` description (~500–700 tokens saved) — *partial: compressed in `05d1af3`*
+The tool description re-lists all 18 types with required sections (~700 tokens) that already exist in system instructions. The compressed shipped version keeps a one-line summary per type; a future change could replace with a single reference: "See system instructions for required sections per type."
 
-### 2. Remove `filename` + `slug` from `list_documents` response (~430 tokens per 50 docs)
+### 2. Remove `filename` + `slug` from `list_documents` response (~430 tokens per 50 docs) — *open*
 Both are mechanically derivable from `path`. Strip from JSON response.
 
-### 3. Strip frontmatter from `content` in `get_document` response (~10–14 tokens/call)
+### 3. Strip frontmatter from `content` in `get_document` response (~10–14 tokens/call) — *open*
 `title` and `status` are already decoded as separate JSON fields. The raw frontmatter inside `content` is redundant.
 
-### 4. Consolidate requirements tracks + layers + type selection (~150–200 tokens)
+### 4. Consolidate requirements tracks + layers + type selection (~150–200 tokens) — *open*
 Three overlapping blocks cover similar disambiguation ground. Merge into a single compact reference table.
 
-### 5. Cap `nearby_documents` in `create_document` response (up to ~286 tokens saved)
-In directories with 20+ documents, the hint array grows unbounded. Cap at 5 entries.
+### 5. Cap `nearby_documents` in `create_document` response (up to ~286 tokens saved) — *shipped in `05d1af3`*
+Capped at 5 entries, sorted alphabetically.
 
 ## Risks and Constraints
 
-- **Deduplication risk**: Some LLMs weight tool-level descriptions higher than system instructions. Removing type info from `create_document` may reduce accuracy for models that prioritize tool schemas over system prompt. Needs A/B testing.
+- **Deduplication risk**: Some LLMs weight tool-level descriptions higher than system instructions. Removing type info from `create_document` may reduce accuracy for models that prioritize tool schemas over system prompt. Needs A/B testing. The compressed form shipped in `05d1af3` is a hedge against this risk.
 - **Stripping frontmatter from get_document**: Changes the contract — agents that parse `content` expecting frontmatter will break. Requires migration path or a `raw` parameter.
 - **Consolidating disambiguation rules**: The current verbose format is optimized for LLM comprehension. A compact table may reduce readability for the model. Test with edge cases (brs vs brd, strs vs urd).
-- **Session-start context scales with repo size**: The document list and relations summary grow linearly. This analysis covers the fixed prompt; the scaling overhead is a separate concern.
+- **Session-start context scales with repo size**: The document list and relations summary grow linearly. This analysis covers the fixed prompt; the scaling overhead is a separate concern.

.archcore/integrations/agent-hooks-integration.guide.md

@@ -218,6 +218,29 @@ Cline stores MCP config in VS Code `globalStorage`, not in project files. To add
 1. Open Cline MCP settings in VS Code
 2. Add an MCP server with command `archcore` and args `["mcp"]`
 
+## Pointing the MCP Server at a Specific Project Root
+
+By default `archcore mcp` serves documents from the current working directory. Some editor integrations launch the binary from a directory that isn't the workspace root (e.g. a desktop app's install dir, or a Cline globalStorage profile). In those cases the server may see an empty/wrong project.
+
+Two overrides are available:
+
+- **Flag**: `archcore mcp --project /absolute/path/to/repo`
+- **Environment**: `ARCHCORE_PROJECT_ROOT=/absolute/path/to/repo archcore mcp`
+
+Precedence: `--project` > `ARCHCORE_PROJECT_ROOT` > current working directory.
+
+The path must point at an existing directory (it does not need to contain `.archcore/` yet — the server still starts and exposes `init_project`).
+
+Example for an agent that needs an absolute workspace path:
+
+```json
+{
+  "mcpServers": {
+    "archcore": { "command": "archcore", "args": ["mcp", "--project", "/Users/me/code/my-repo"] }
+  }
+}
+```
+
 ## Invalid Config Recovery
 
 When archcore reads a config file that contains invalid JSON, it creates a `.bak` backup before proceeding with a fresh config. This prevents data loss while keeping the installation non-blocking.
@@ -233,6 +256,14 @@ See [Backup Invalid Configs](backup-invalid-configs.adr.md) for the full decisio
 - The **MCP server** (`archcore mcp`) starts fine without `.archcore/` — it exposes `init_project` so the agent can bootstrap the directory in-session. If the agent sees an empty `list_documents` result and wants to create documents, it should call `init_project` first.
 - **Hooks** and the `archcore hooks/mcp install` commands still require an initialized project. Run `archcore init` first, or ask the agent to call `init_project`.
 
+### MCP server is serving the wrong directory
+
+Symptoms: `list_documents` returns an empty array even though the workspace clearly has `.archcore/` documents, or `init_project` would create the directory in an unexpected location.
+
+Cause: the agent launched `archcore mcp` from a working directory that isn't your workspace.
+
+Fix: pass `--project` explicitly in the agent's MCP config, or set `ARCHCORE_PROJECT_ROOT` in the agent's environment. See **Pointing the MCP Server at a Specific Project Root** above.
+
 ### Agent not detected
 
 Check that the agent's marker directory exists in your project root. You can also target a specific agent with `--agent`:

.archcore/mcp/mcp-server-starts-without-archcore-dir.adr.md

@@ -16,7 +16,7 @@ Two user flows were affected:
 
 ## Decision
 
-1. **`archcore mcp` starts unconditionally.** The `.archcore/` existence check in `cmd/mcp.go` is removed. The server always boots on stdio and prints a hint in the startup banner when the directory is missing.
+1. **`archcore mcp` starts unconditionally for the default (cwd) project root.** The `.archcore/` existence check in `cmd/mcp.go` is removed. The server always boots on stdio and prints a hint in the startup banner when the directory is missing.
 2. **Add an `init_project` MCP tool** (`internal/mcp/tools/init_project.go`). It creates `.archcore/` and writes `settings.json` from within the MCP server itself. It accepts `language`, `sync_mode`, and `archcore_url` and is idempotent — calling it on an already-initialized project returns the existing settings without overwriting them.
 3. **Server instructions document the bootstrap flow.** The system prompt embedded in `internal/mcp/server.go` (`mcpServerInstructions`) explicitly tells the agent: "if `list_documents` returns empty AND the user wants to create documents, call `init_project` once, then proceed."
 4. **Other tools continue to assume `.archcore/` exists.** `create_document`, `list_documents`, `update_document`, etc. are not changed to auto-init. The only tool safe to call on an uninitialized project is `init_project`.
@@ -40,3 +40,12 @@ Negative / constraints:
 - The MCP server now has a "degraded" mode (running, but most tools will fail). The startup banner's hint compensates, but agents that ignore system prompts may attempt `create_document` before `init_project` and see confusing errors. Mitigated by the explicit instruction block in `mcpServerInstructions`.
 - `init_project` must stay idempotent. A regression that clobbers existing `settings.json` on the second call would destroy user configuration. Covered by `TestHandleInitProject_Idempotent`.
 - Any future MCP tool that *also* safely works on an uninitialized project must be documented in the server instructions alongside `init_project`. Today that list is just `init_project`.
+
+### Scope of the "unconditional start" property
+
+The unconditional-start guarantee applies to the **default project root** (cwd) and to the case where `.archcore/` is missing inside an existing project directory. It does **not** override the project-root resolution layer:
+
+- When `--project <path>` is passed to `archcore mcp`, or `ARCHCORE_PROJECT_ROOT` is set, the resolver (`cmd/mcp_root.go`) requires the path to exist and to be a directory. A missing or non-directory path causes the command to exit before the server starts.
+- This is intentional: if the user explicitly names a project root, silently falling back to cwd would be more surprising than failing fast. `.archcore/` *inside* the resolved root may still be absent — the server still starts in that case and exposes `init_project`.
+
+In short: the server tolerates a missing `.archcore/`, but does not tolerate a missing project directory the user explicitly named.

.archcore/release/how-to-release.guide.md

@@ -35,34 +35,41 @@ status: accepted
 
    The GitHub Actions workflow (`.github/workflows/release.yml`) triggers automatically. It will:
    - Run `go test ./...`
-   - Build binaries for darwin/linux × amd64/arm64
+   - Build binaries for darwin/linux/windows × amd64/arm64 (6 platforms)
    - Create a GitHub Release with archives and `checksums.txt`
 
    Watch progress at: `https://github.com/archcore-ai/cli/actions`
 
 5. **Verify the release**
 
    ```bash
-   # Check the GitHub Release page has all 5 assets (4 archives + checksums.txt)
+   # Check the GitHub Release page has all 7 assets (6 archives + checksums.txt)
    gh release view v1.0.0
 
-   # Test the install script
+   # Test the install script (macOS/Linux)
    ARCHCORE_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/archcore-ai/cli/main/install.sh | bash
 
+   # Test the install script (Windows PowerShell)
+   $env:ARCHCORE_VERSION="v1.0.0"; irm https://raw.githubusercontent.com/archcore-ai/cli/main/install.ps1 | iex
+
    # Verify the installed binary
    archcore --version
    # Expected: archcore 1.0.0 (commit: <sha>)
    ```
 
 ## Verification
 
-- GitHub Release page shows 4 `.tar.gz` archives + `checksums.txt`
+- GitHub Release page shows 6 archives (4 `.tar.gz` for darwin/linux amd64+arm64, 2 `.zip` for windows amd64+arm64) plus `checksums.txt`
 - `archcore --version` on installed binary shows correct version and commit
-- Install script succeeds on a clean machine
+- Install script succeeds on a clean macOS/Linux machine
+- `install.ps1` succeeds on a clean Windows machine
+
+See [Release Infrastructure Overview](release-infrastructure.doc.md) for the full build matrix, artifact naming, and update paths.
 
 ## Common Issues
 
 - **Workflow fails at test step** — Fix the tests on `main`, delete the tag (`git push origin :v1.0.0 && git tag -d v1.0.0`), then re-tag after fixing.
 - **GoReleaser fails** — Check `.goreleaser.yaml` syntax. Run `goreleaser check` locally if available.
 - **Wrong commit tagged** — Delete the remote tag, re-tag the correct commit, and push again.
-- **install.sh can't find the release** — Ensure the tag follows the `v*` pattern (e.g. `v1.0.0`, not `1.0.0`).
+- **install.sh / install.ps1 can't find the release** — Ensure the tag follows the `v*` pattern (e.g. `v1.0.0`, not `1.0.0`).
+- **Windows zips missing from release** — Confirm `.goreleaser.yaml` `format_overrides` still maps `windows` to `zip`; otherwise GoReleaser will fall back to `.tar.gz` and `install.ps1` won't find the expected archives.

README.md

@@ -301,6 +301,8 @@ Archcore does not require a hosted service. The CLI runs a local stdio MCP serve
 archcore mcp
 ```
 
+By default `archcore mcp` serves documents from the current directory. Pass `--project /path/to/repo` (or set `ARCHCORE_PROJECT_ROOT`) to point it elsewhere — useful when the server is launched from a directory that isn't your workspace (for example, by an editor integration).
+
 Wire it into Claude Code:
 
 ```bash

cmd/mcp.go

@@ -14,55 +14,65 @@ import (
 )
 
 func newMCPCmd() *cobra.Command {
+	var projectFlag string
+
 	cmd := &cobra.Command{
 		Use:   "mcp",
 		Short: "MCP stdio server for archcore documents",
 		Long:  "Starts an MCP (Model Context Protocol) stdio server that exposes archcore document tools.",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			cwd, err := os.Getwd()
+			baseDir, err := resolveProjectRoot(projectFlag, os.Getenv("ARCHCORE_PROJECT_ROOT"))
 			if err != nil {
 				return err
 			}
 
 			fmt.Fprintln(os.Stderr, display.WelcomeBanner())
 			fmt.Fprintln(os.Stderr)
-			if !config.DirExists(cwd) {
+			if !config.DirExists(baseDir) {
 				fmt.Fprintln(os.Stderr, display.Dim.Render("  MCP server running on stdio (uninitialized project — only init_project tool is useful until the agent initializes .archcore/)..."))
 			} else {
 				fmt.Fprintln(os.Stderr, display.Dim.Render("  MCP server running on stdio..."))
 			}
 
-			return mcpserver.RunStdio(cwd)
+			return mcpserver.RunStdio(baseDir)
 		},
 	}
 
+	cmd.Flags().StringVar(&projectFlag, "project", "",
+		"project root containing .archcore/ (default: current directory; env: ARCHCORE_PROJECT_ROOT)")
+
 	cmd.AddCommand(newMCPInstallCmd())
 	return cmd
 }
 
 func newMCPInstallCmd() *cobra.Command {
-	var agentFlag string
+	var (
+		agentFlag   string
+		projectFlag string
+	)
 
 	cmd := &cobra.Command{
 		Use:   "install",
 		Short: "Install MCP server config for coding agents",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			cwd, err := os.Getwd()
+			baseDir, err := resolveProjectRoot(projectFlag, os.Getenv("ARCHCORE_PROJECT_ROOT"))
 			if err != nil {
 				return err
 			}
-			if !config.DirExists(cwd) {
+			if !config.DirExists(baseDir) {
 				return errors.New(".archcore/ not found — run 'archcore init' first")
 			}
 
 			if agentFlag != "" {
-				return runMCPInstallForAgent(cwd, agents.AgentID(agentFlag))
+				return runMCPInstallForAgent(baseDir, agents.AgentID(agentFlag))
 			}
-			return runMCPInstallAutoDetect(cwd)
+			return runMCPInstallAutoDetect(baseDir)
 		},
 	}
 
 	cmd.Flags().StringVar(&agentFlag, "agent", "", "install for a specific agent (e.g. cursor, gemini-cli)")
+	cmd.Flags().StringVar(&projectFlag, "project", "",
+		"project root containing .archcore/ (default: current directory; env: ARCHCORE_PROJECT_ROOT)")
 	return cmd
 }
 

cmd/mcp_root.go

@@ -0,0 +1,54 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+)
+
+// resolveProjectRoot picks the project root from (in order):
+//   1. flagValue if non-empty
+//   2. envValue if non-empty
+//   3. os.Getwd()
+//
+// The returned path is absolute. Errors if the source cannot be made absolute,
+// does not exist, or is not a directory.
+//
+// envValue is passed in (not read inside) so the caller controls precedence
+// visibly and tests do not have to mutate process env.
+func resolveProjectRoot(flagValue, envValue string) (string, error) {
+	var source string
+	switch {
+	case flagValue != "":
+		source = flagValue
+	case envValue != "":
+		source = envValue
+	default:
+		cwd, err := os.Getwd()
+		if err != nil {
+			return "", fmt.Errorf("failed to determine working directory: %w", err)
+		}
+		source = cwd
+	}
+
+	abs, err := filepath.Abs(source)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve project root %q: %w", source, err)
+	}
+
+	info, err := os.Stat(abs)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return "", fmt.Errorf("project root does not exist: %q", abs)
+		}
+		return "", fmt.Errorf("failed to stat project root %q: %w", abs, err)
+	}
+
+	if !info.IsDir() {
+		return "", fmt.Errorf("project root is not a directory: %q", abs)
+	}
+
+	return abs, nil
+}