From 757f38509e4e08b8f35f189820336d59b9bc9fa9 Mon Sep 17 00:00:00 2001 From: lukealvoeiro Date: Tue, 13 Oct 2026 00:40:29 +0000 Subject: [PATCH] chore(cli): correct MCP server layering precedence in docs The MCP configuration page said user config wins over folder and project config, and that folder-level mcp.json is read from ancestor directories of the project. The CLI resolves MCP servers through the general settings hierarchy (org > folder > project > user, reordered deliberately in factory-mono #10094), and folder levels are the .factory directories between the working directory and the git root. Update the EN page and the JP mirror to describe the actual behavior. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/cli/configuration/mcp.mdx | 4 ++-- docs/jp/cli/configuration/mcp.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli/configuration/mcp.mdx b/docs/cli/configuration/mcp.mdx index 8fc47fd8..6fc620df 100644 --- a/docs/cli/configuration/mcp.mdx +++ b/docs/cli/configuration/mcp.mdx @@ -261,14 +261,14 @@ MCP server configurations are loaded from local files at the following levels: | Level | Location | Purpose | | :---- | :------- | :------ | | **User** | `~/.factory/mcp.json` | Your personal servers, available in all projects | -| **Folder** | `.factory/mcp.json` in any ancestor directory of the project | Servers shared across nested projects under a common parent folder | +| **Folder** | `.factory/mcp.json` in a subdirectory between your working directory and the project root | Servers scoped to part of a repository, such as one package in a monorepo | | **Project** | `.factory/mcp.json` in the project root | Shared team servers, committed to the repo | Organization administrators can also centrally provide servers and restrict which ones are allowed via organization-managed settings (see [Enterprise MCP policy](#enterprise-mcp-policy)). ### How Layering Works -When the same server is defined at multiple levels, user config takes priority, followed by folder-level config, then project config. +When the same server is defined at multiple levels, folder-level config takes priority (the folder closest to your working directory wins), followed by project config, then user config. Servers provided by organization-managed settings take priority over all local levels. **Key behaviors:** - When you **enable/disable** a project-defined server, a copy is saved to your user config with the new state. The original project config remains unchanged, so your teammates aren't affected. diff --git a/docs/jp/cli/configuration/mcp.mdx b/docs/jp/cli/configuration/mcp.mdx index 1f3e658e..0e239535 100644 --- a/docs/jp/cli/configuration/mcp.mdx +++ b/docs/jp/cli/configuration/mcp.mdx @@ -261,14 +261,14 @@ MCPサーバー設定は、次のレベルのローカルファイルから読 | レベル | 場所 | 目的 | | :---- | :------- | :------ | | **ユーザー** | `~/.factory/mcp.json` | 個人のサーバー、すべてのプロジェクトで利用可能 | -| **フォルダ** | プロジェクトの任意の祖先ディレクトリにある `.factory/mcp.json` | 共通の親フォルダ配下のネストしたプロジェクト間で共有するサーバー | +| **フォルダ** | 作業ディレクトリとプロジェクトルートの間にあるサブディレクトリの `.factory/mcp.json` | モノレポ内の特定のパッケージなど、リポジトリの一部に限定したサーバー | | **プロジェクト** | プロジェクトルートの `.factory/mcp.json` | チーム共有サーバー、リポジトリにコミット | 組織管理者は、組織管理設定を通じてサーバーを一元提供し、許可するサーバーを制限することもできます（[Enterprise MCP ポリシー](#enterprise-mcp-policy) を参照）。 ### レイヤー化の仕組み -同じサーバーが複数レベルで定義されている場合は、ユーザー設定、フォルダレベル設定、プロジェクト設定の順に優先されます。 +同じサーバーが複数レベルで定義されている場合は、フォルダレベル設定（作業ディレクトリに最も近いフォルダが優先）、プロジェクト設定、ユーザー設定の順に優先されます。組織管理設定で提供されるサーバーは、すべてのローカルレベルより優先されます。 **重要な動作：** - プロジェクト定義のサーバーを**有効化/無効化**すると、新しい状態でコピーがユーザー設定に保存されます。元のプロジェクト設定は変更されないため、チームメンバーには影響しません。