Struct ProjectAtlasMcpServer 

pub(crate) struct ProjectAtlasMcpServer {
    control_state: McpProjectState,
    project_state: Arc<RwLock<McpProjectState>>,
    session: String,
    usage_runtime: Arc<Mutex<McpUsageRuntime>>,
    allow_nearest_project: bool,
    task_registry: Arc<RwLock<McpTaskRegistry>>,
    background_resources: McpBackgroundResourceEnvelope,
    next_task_sequence: Arc<AtomicU64>,
    source_observations: Arc<SourceObservationRegistry>,
    tool_router: ToolRouter<Self>,
}

Native ProjectAtlas MCP server backed by the same services as the CLI.

Fields

control_state: McpProjectState

Immutable registry/control authority selected when the MCP process started.

project_state: Arc<RwLock<McpProjectState>>

Active project state for calls that omit project_path.

session: String

Caller-visible compatibility label applied to this MCP process’s events.

usage_runtime: Arc<Mutex<McpUsageRuntime>>

Bounded telemetry lifecycle shared by every server clone and routed project.

allow_nearest_project: bool

Whether absolute path arguments may select the nearest indexed project by default.

task_registry: Arc<RwLock<McpTaskRegistry>>

Bounded MCP task-progress records for this server session.

background_resources: McpBackgroundResourceEnvelope

Fixed aggregate worker partition for background indexing tasks.

next_task_sequence: Arc<AtomicU64>

Monotonic session-local task identifier source.

source_observations: Arc<SourceObservationRegistry>

Bounded per-project source observers and verified read epochs.

tool_router: ToolRouter<Self>

Official RMCP tool router.

Implementations

impl ProjectAtlasMcpServer

pub(crate) fn new( db_path: PathBuf, config_path: Option<PathBuf>, session: String, allow_nearest_project: bool, ) -> Self

Create a ProjectAtlas MCP server instance.

fn open_read_store(state: &McpProjectState) -> Result<AtlasStore, CliError>

Open the durable index through one root-bound read snapshot.

fn require_initialized_worktree_target( state: &McpProjectState, ) -> Result<(), CliError>

Require registered worktree aliases to be initialized outside atlas_init.

fn with_target_error_context( error: CliError, state: &McpProjectState, ) -> CliError

Preserve a captured worktree alias on typed init/refresh recovery state.

fn with_fresh_store_for_request<T, F>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, query: F, ) -> Result<VerifiedReadOutcome<T>, CliError>

where F: FnMut(&AtlasStore, VerifiedReadStamp) -> Result<T, CliError>,

Run one verified query with optional RMCP request cancellation bridging.

fn with_fresh_store_controlled_for_request<T, F>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, query: F, ) -> Result<VerifiedReadOutcome<T>, CliError>

where F: FnMut(&AtlasStore, VerifiedReadStamp, &IndexWorkControl) -> Result<T, CliError>,

Run one verified query that consumes the request cancellation boundary.

fn require_captured_worktree_identity( selection: Option<&McpWorktreeSelection>, store: &AtlasStore, ) -> Result<(), CliError>

Revalidate one alias selection against the exact opened read snapshot.

fn require_captured_control_identity( selection: Option<&McpWorktreeSelection>, control: &AtlasStore, ) -> Result<(), CliError>

Revalidate the control catalog that owns one captured alias registration.

fn require_federated_worktree_identities( stores: Vec<FederatedStore>, selections: &[McpWorktreeSelection], ) -> Result<Vec<FederatedStore>, CliError>

Admit only federation snapshots that retain their captured alias identities.

fn with_fresh_string_for_request<F>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, query: F, ) -> Result<String, CliError>

where F: FnMut(&AtlasStore, VerifiedReadStamp) -> Result<String, CliError>,

Run one rendered MCP query with request cancellation bridged into index work.

fn with_fresh_string_and_usage_for_request<F>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, query: F, ) -> Result<String, CliError>

where F: FnMut(&AtlasStore, VerifiedReadStamp) -> Result<(String, Option<McpUsageIntent>), CliError>,

Record optional usage only after source and SQLite result acceptance succeeds.

fn with_fresh_string_and_usage_controlled_for_request<F>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, query: F, ) -> Result<String, CliError>

where F: FnMut(&AtlasStore, VerifiedReadStamp, &IndexWorkControl) -> Result<(String, Option<McpUsageIntent>), CliError>,

Render one verified MCP query that consumes request cancellation.

fn open_mut_store( state: &McpProjectState, control_state: &McpProjectState, ) -> Result<AtlasStore, CliError>

Open the durable index for mutation and bind any migrated alias identity first.

fn open_registered_worktree_mut_store( state: &McpProjectState, control_state: &McpProjectState, selection: &McpWorktreeSelection, ) -> Result<AtlasStore, CliError>

Open and, when needed, bind one alias under exact control-writer exclusion.

fn open_existing_mut_store( state: &McpProjectState, control_state: &McpProjectState, ) -> Result<AtlasStore, CliError>

Open an existing selected-project index for purpose or health mutation.

fn with_admitted_purpose_mutation<T>( &self, state: &McpProjectState, context: Option<RequestContext<RoleServer>>, mutation: impl FnOnce(&AtlasStore) -> Result<T, CliError>, ) -> Result<T, CliError>

Apply one purpose mutation under a source witness retained through commit.

fn with_admitted_purpose_mutation_controlled<T>( &self, state: &McpProjectState, control: &IndexWorkControl, bridge: Option<&McpRequestCancellationBridge>, mutation: impl FnOnce(&AtlasStore) -> Result<T, CliError>, ) -> Result<T, CliError>

Apply one admitted mutation with explicit cancellation and rollback boundaries.

fn telemetry_enabled() -> bool

Return whether this MCP process can record optional telemetry.

fn record_usage_for_state<F>( &self, state: &McpProjectState, store: &AtlasStore, record: F, )

where F: FnMut(UsageRuntimeInstance) -> Result<(), CliError>,

Record telemetry and rotate only this project’s scope if baselines are full.

fn record_usage_for_origin<F>( &self, state: &McpProjectState, store: &AtlasStore, worktree_registration_id: Option<i64>, record: F, )

where F: FnMut(UsageRuntimeInstance) -> Result<(), CliError>,

Record telemetry under one exact authority and optional worktree origin.

fn record_accepted_usage( &self, state: &McpProjectState, stamp: &VerifiedReadStamp, intent: &McpUsageIntent, output: &str, )

Best-effort telemetry for one result whose source epoch has already been accepted.

fn estimated_source_tokens_cached( &self, state: &McpProjectState, store: &AtlasStore, stamp: &VerifiedReadStamp, folder: Option<&str>, file_pattern: Option<&str>, ) -> Result<usize, CliError>

Reuse an optional broad-source telemetry baseline within one complete generation.

fn seal_usage_instances_for_projects(&self)

Best-effort seal each selected project’s current identity at shutdown.

fn load_config_for_state( state: &McpProjectState, ) -> Result<AtlasMapConfig, CliError>

Load effective atlas config for the selected state.

fn init_project_root( &self, project_path: Option<String>, worktree: Option<String>, ) -> Result<McpProjectState, CliError>

Return the selected project root used by initialization.

fn run_registered_worktree_init( &self, state: &McpProjectState, config_path: &Path, options: &InitBootstrapOptions, ) -> Result<InitSetupReport, CliError>

Initialize one registered worktree, preferring a reconciled control-atlas baseline.

fn attempt_worktree_hydration( &self, state: &McpProjectState, config_path: &Path, options: &InitBootstrapOptions, ) -> Result<McpWorktreeHydration, CliError>

Build, reconcile, and no-clobber activate one private hydration candidate.

fn activate_registered_worktree_hydration( &self, state: &McpProjectState, selection: &McpWorktreeSelection, candidate: PreparedWorktreeHydrationCandidate, work_control: &IndexWorkControl, ) -> Result<WorktreeHydrationActivation, CliError>

Publish one prepared hydration candidate only for the still-exact registered lifecycle.

fn activate_registered_worktree_hydration_with_post_publication<F>( &self, state: &McpProjectState, selection: &McpWorktreeSelection, candidate: PreparedWorktreeHydrationCandidate, work_control: &IndexWorkControl, post_publication: F, ) -> Result<WorktreeHydrationActivation, CliError>

where F: FnOnce() -> Result<(), CliError>,

Publish and bind a verified candidate with one deterministic final-admission seam.

fn bind_initialized_worktree( &self, selection: &McpWorktreeSelection, state: &McpProjectState, ) -> Result<(), CliError>

Bind a successfully initialized alias to its exact local atlas identity.

fn bind_initialized_registration_for_root( &self, state: &McpProjectState, ) -> Result<(), CliError>

Bind a legacy exact-path init when its root already has an active alias.

fn hydration_can_fallback(error: &CliError) -> bool

Preserve cancellation/resource failures and fallback only for unusable source baselines.

fn hydration_db_error(error: DbError) -> CliError

Lift database-owned cancellation into the shared CLI work-control error.

fn admin_project_root( &self, project_path: Option<String>, worktree: Option<String>, ) -> Result<McpProjectState, CliError>

Return the initialized selected project root used by admin-style MCP calls.

fn parse_ignore_kind( kind: Option<&str>, required: bool, ) -> Result<Option<IgnoreEntryKind>, CliError>

Parse an MCP ignore kind parameter.

fn parse_purpose_lint_level( value: Option<&str>, ) -> Result<PurposeLintLevel, CliError>

Parse an MCP purpose lint level parameter.

fn parse_harness_config(value: Option<&str>) -> Result<HarnessConfig, CliError>

Parse an MCP harness config parameter.

fn parse_token_chart_theme( value: Option<&str>, ) -> Result<TokenDashboardTheme, CliError>

Parse the optional token chart theme parameter.

fn invalid_parameter_message(prefix: &str, value: &str, suffix: &str) -> String

Build an invalid-parameter diagnostic from centralized fragments.

fn build_map_report( state: &McpProjectState, json: bool, force: bool, ) -> Result<McpMapReport, CliError>

Build a compatibility map report, writing the map unless CI skip policy applies.

fn session_capabilities( &self, state: &McpProjectState, text_index_max_bytes: u64, ) -> McpSessionCapabilities

Build typed MCP session capabilities from active server state.

fn render_settings_with_capabilities( &self, state: &McpProjectState, ) -> Result<String, CliError>

Encode settings plus additive MCP-session capability fields.

fn selected_project_capability( state: &McpProjectState, ) -> McpSelectedProjectCapability

Build the selected-project capability row.

fn path_scope(&self) -> McpPathScope

Return the path scope for this MCP server.

fn policy_state(enabled: bool) -> McpPolicyState

Convert a bool into a serialized policy state.

fn brief_limit(value: Option<usize>) -> usize

Clamp a caller-provided brief limit to the supported range.

fn build_session_brief( &self, params: AtlasSessionBriefParams, context: Option<RequestContext<RoleServer>>, ) -> Result<McpSessionBrief, CliError>

Build a read-only agent startup brief.

fn brief_policy(&self) -> McpBriefPolicy

Build brief policy fields.

fn build_compact_session_brief( &self, params: AtlasSessionBriefParams, context: Option<RequestContext<RoleServer>>, ) -> Result<McpCompactSessionBrief, CliError>

Build the additive compact projection without changing legacy defaults or query behavior.

fn compact_session_brief( brief: &McpSessionBrief, project_path: Option<&str>, worktree: Option<&str>, ) -> McpCompactSessionBrief

Project the compatibility report into the explicit compact response shape.

fn brief_candidate(row: RankedNode) -> McpBriefCandidate

Convert a ranked node into the compatibility-preserving startup candidate.

fn compact_brief_candidate(row: &McpBriefCandidate) -> McpCompactBriefCandidate

Project one compatibility candidate into the bounded compact shape.

fn brief_connection_is_crisp(connection: &RankedConnection) -> bool

Prefer a resolved non-import edge as the single default startup connection sample.

fn compact_brief_purpose_handoff( handoff: &PurposeCuratorHandoff, project_path: Option<String>, worktree: Option<String>, ) -> McpCompactBriefPurposeHandoff

Project an actionable handoff into one exact follow-up call instead of duplicating rows.

fn compact_brief_recommendation( recommendation: &McpBriefRecommendation, ) -> McpCompactBriefRecommendation

Add compact opt-ins to one legacy recommendation without changing its source report.

fn brief_blockers( store: &AtlasStore, blocker_limit: usize, ) -> Result<McpBriefBlockers, CliError>

Build bounded health blockers for a session brief.

fn missing_index_recommendations( project_path: Option<String>, worktree: Option<String>, ) -> Vec<McpBriefRecommendation>

Recommend next calls for a missing index.

fn indexed_project_recommendations( query: &str, next_navigation_call: Option<NavigationNextCall>, blocker_total: usize, blocker_limit: usize, project_path: Option<String>, worktree: Option<String>, ) -> Vec<McpBriefRecommendation>

Recommend next calls for an indexed project.

fn target_arguments( project_path: Option<String>, worktree: Option<String>, ) -> Value

Build a JSON object containing one mutually exclusive root selector.

fn brief_call_arguments( project_path: Option<String>, worktree: Option<String>, string_args: &[(&'static str, &str)], usize_arg: Option<(&'static str, usize)>, ) -> Value

Build recommendation call arguments with optional project path and one payload argument.

fn task_state_values() -> Vec<McpTaskState>

Return all task model states for contract discovery.

fn task_operation_values() -> Vec<McpTaskOperation>

Return all task operation values for contract discovery.

fn start_index_task<F>( &self, operation: McpTaskOperation, options: SymbolBuildOptions, result_ref: &'static str, work: F, ) -> Result<McpTaskStartResponse, CliError>

where F: FnOnce(&IndexWorkControl, SymbolBuildOptions) -> Result<(), CliError> + Send + 'static,

Start one bounded session-local indexing task.

fn task_status( &self, task_id: String, ) -> Result<McpTaskStatusResponse, CliError>

Look up one MCP task status.

fn task_cancel( &self, task_id: String, ) -> Result<McpTaskCancelResponse, CliError>

Cancel one MCP task when cancellation is supported.

fn lint_report_for_state( state: &McpProjectState, params: &AtlasLintParams, ) -> Result<LintReport, CliError>

Build a CLI-compatible lint report for MCP callers.

fn startup_project_state( db_path: PathBuf, config_path: Option<PathBuf>, ) -> McpProjectState

Build startup state from CLI-supplied DB/config paths.

fn startup_project_root(db_path: &Path, config_path: Option<&Path>) -> PathBuf

Resolve startup root best-effort so server construction stays infallible.

fn project_root_from_default_db_path(db_path: &Path) -> Option<PathBuf>

Infer a root from a conventional root/.projectatlas/projectatlas.db path.

fn active_project_state(&self) -> Result<McpProjectState, CliError>

Read the active MCP project state.

fn set_active_project_state( &self, state: McpProjectState, ) -> Result<(), CliError>

Replace the active MCP project state.

fn control_git_repository(&self) -> Result<GitRepositoryStructure, CliError>

Return the bounded reciprocal Git inventory for the immutable control checkout.

fn control_git_repository_if_present( &self, ) -> Result<Option<GitRepositoryStructure>, CliError>

Return the control Git inventory, or none for a true non-Git control root.

fn worktree_candidate_selector(entry: &GitWorktreeEntry) -> String

Derive one stable, short candidate selector from Git administrative identity.

fn worktree_candidate_selector_from_path(identity: &Path) -> String

Derive one stable selector from a native administrative-directory path.

fn worktree_candidate_selector_from_identity(identity: &str) -> String

Derive one stable, short candidate selector from normalized Git identity text.

fn worktree_candidate_selector_from_native_identity(identity: &[u8]) -> String

Derive a selector from exact native administrative-directory bytes.

fn worktree_candidate_selector_from_canonical_identity( identity: &CanonicalProjectRoot, ) -> String

Derive the same selector from a persisted native identity that a live Git entry would expose, retaining the exact bytes when UTF-8 display is unavailable.

fn active_worktree_root(entry: &GitWorktreeEntry) -> Option<&Path>

Borrow one active source root from structural worktree evidence.

fn worktree_candidate_matches(entry: &GitWorktreeEntry, selector: &str) -> bool

Return whether one short selector identifies this structural candidate.

fn matching_worktree_candidates<'a>( &'a self, repository: &'a GitRepositoryStructure, selector: &str, ) -> Vec<&'a GitWorktreeEntry>

Return bounded active non-control candidates for one stable or human selector.

fn revalidate_worktree_candidate( &self, expected_repository: &GitRepositoryStructure, expected_entry: &GitWorktreeEntry, expected_identity: &str, ) -> Result<(GitRepositoryStructure, GitWorktreeEntry), CliError>

Revalidate one selected candidate and its filesystem lifecycle before registration.

fn worktree_candidate( common_directory: &Path, entry: &GitWorktreeEntry, ) -> Option<McpWorktreeCandidate>

Build one concise add-candidate row from active structural evidence.

fn default_worktree_alias(root: &Path) -> Result<WorktreeAlias, CliError>

Derive a valid default alias from one selected active worktree root.

fn open_local_worktree_atlas( root: &Path, ) -> Result<Option<AtlasStore>, CliError>

Open one exact local worktree atlas without creating or migrating it.

fn local_worktree_project_instance_id( store: &AtlasStore, db_path: &Path, ) -> Result<ProjectInstanceId, CliError>

Require the exact project identity from one already-open local atlas.

fn local_worktree_usage_snapshot( store: &AtlasStore, db_path: &Path, project_instance_id: ProjectInstanceId, ) -> Result<WorktreeUsageSnapshot, CliError>

Export one local usage snapshot bound to an independently read project identity.

fn local_worktree_atlas( root: &Path, ) -> Result<Option<LocalWorktreeAtlas>, CliError>

Read one exact local worktree atlas and its bounded telemetry snapshot without migration.

fn revalidate_local_worktree_atlas_identity( root: &Path, expected: Option<ProjectInstanceId>, ) -> Result<(), CliError>

Reopen an identity-bound local atlas before its registration is committed.

fn retire_registered_worktree( control: &AtlasStore, registration: &WorktreeRegistration, root: Option<&Path>, retired_at_epoch: u64, initial_blocker: Option<String>, ) -> Result<(WorktreeRegistration, Option<WorktreeUsageSyncState>, Option<String>), CliError>

Finalize one retirement under control-first writer exclusion.

fn retire_registered_worktree_with_pre_open<F>( control: &AtlasStore, registration: &WorktreeRegistration, root: Option<&Path>, retired_at_epoch: u64, initial_blocker: Option<String>, pre_open: F, ) -> Result<(WorktreeRegistration, Option<WorktreeUsageSyncState>, Option<String>), CliError>

where F: FnOnce() -> Result<(), CliError>,

Finalize retirement with one deterministic seam before the local atlas is opened.

fn classify_retirement_failure( guard: &mut ActiveWorktreeRegistrationGuard<'_>, root: &Path, retired_at_epoch: u64, error: CliError, ) -> Result<Result<(WorktreeRegistration, Option<WorktreeUsageSyncState>, Option<String>), CliError>, DbError>

Preserve an unchanged database error or retire a replaced Git lifecycle.

fn retire_changed_worktree_lifecycle( guard: &mut ActiveWorktreeRegistrationGuard<'_>, retired_at_epoch: u64, ) -> Result<(WorktreeRegistration, Option<WorktreeUsageSyncState>, Option<String>), DbError>

Retire a stale registration without binding, importing, or modifying replacement state.

fn reset_registered_worktree_index( &self, state: &McpProjectState, selection: &McpWorktreeSelection, include_mcp_config: bool, ) -> Result<ResetIndexReport, CliError>

Reset one unbound alias while excluding concurrent bind or retirement publication.

fn reset_registered_worktree_index_with_post_validation<F>( &self, state: &McpProjectState, selection: &McpWorktreeSelection, include_mcp_config: bool, post_validation: F, ) -> Result<ResetIndexReport, CliError>

where F: FnOnce() -> Result<(), CliError>,

Reset one unbound alias with a deterministic post-validation seam.

fn worktree_administrative_path_identity( entry: &GitWorktreeEntry, ) -> Option<CanonicalProjectRoot>

Match invalid evidence by its retained path without following a replacement target.

fn worktree_list_row( &self, common_directory: &Path, entry: &GitWorktreeEntry, registrations: &[WorktreeRegistration], ) -> McpWorktreeRow

Join one structural worktree entry to registry, atlas, and telemetry state.

fn missing_registered_worktree_row( registration: &WorktreeRegistration, ) -> McpWorktreeRow

Preserve one active alias when Git no longer reports its worktree registration.

fn current_epoch_seconds() -> Result<u64, CliError>

Return the current Unix epoch seconds within the persisted SQLite domain.

fn state_for_target( &self, project_path: Option<String>, worktree: Option<String>, ) -> Result<McpProjectState, CliError>

Return active/legacy state or one captured registered alias target.

fn federated_worktree_roots( &self, worktrees: &[String], ) -> Result<(Vec<PathBuf>, Vec<McpWorktreeSelection>), CliError>

Resolve an ordered alias federation into exact initialized roots and identities.

fn state_for_target_with_config_validation( &self, project_path: Option<String>, worktree: Option<String>, validation: McpConfigValidation, ) -> Result<McpProjectState, CliError>

Resolve one mutually exclusive target under the selected config-validation timing.

fn resolve_registered_worktree( &self, alias: &WorktreeAlias, validation: McpConfigValidation, ) -> Result<McpProjectState, CliError>

Resolve one active registration through current reciprocal Git structure.

fn state_for_project_path_with_config_validation( &self, project_path: Option<String>, validation: McpConfigValidation, ) -> Result<McpProjectState, CliError>

Return project state under the requested configuration-validation timing.

fn nearest_project_enabled(&self, override_value: Option<bool>) -> bool

Return the nearest-project policy for one call, honoring explicit overrides.

fn state_and_root_path( &self, project_path: Option<String>, worktree: Option<String>, path: Option<String>, nearest_project: bool, ) -> Result<(McpProjectState, PathBuf), CliError>

Return selected state and validate an optional root assertion.

fn background_state_and_root_path( &self, project_path: Option<String>, worktree: Option<String>, path: Option<String>, nearest_project: bool, ) -> Result<(McpProjectState, PathBuf), CliError>

Select a background project without reading configuration before task admission.

fn state_and_root_path_with_config_validation( &self, project_path: Option<String>, worktree: Option<String>, path: Option<String>, nearest_project: bool, validation: McpConfigValidation, ) -> Result<(McpProjectState, PathBuf), CliError>

Select project state and validate a root assertion under one config timing policy.

fn absolute_path_inside_selected_root( state: &McpProjectState, path: &str, ) -> Result<bool, CliError>

Return whether a root assertion path is inside the selected root but not root-equivalent.

fn nearest_root_state_for_root_argument_with_config_validation( path: &Path, validation: McpConfigValidation, ) -> Result<Option<McpProjectState>, CliError>

Return nearest indexed root under one configuration-validation timing policy.

fn state_and_file_key( &self, project_path: Option<&str>, worktree: Option<&str>, file: &str, nearest_project: bool, ) -> Result<McpResolvedRepoPath, CliError>

Return state and a repository-relative file key for an MCP file argument.

fn state_and_optional_file_key( &self, project_path: Option<&str>, worktree: Option<&str>, file: Option<&str>, nearest_project: bool, ) -> Result<(McpProjectState, Option<String>, bool), CliError>

Return state and an optional repository-relative file key for MCP symbol arguments.

fn state_and_optional_folder_filter( &self, project_path: Option<&str>, worktree: Option<&str>, folder: Option<&str>, nearest_project: bool, ) -> Result<(McpProjectState, Option<String>, bool), CliError>

Return state and an optional folder filter for MCP file-ranking arguments.

fn nearest_state_and_repo_key( active_state: &McpProjectState, path: &str, ) -> Result<Option<McpResolvedRepoPath>, CliError>

Resolve an absolute addressed path to the nearest indexed project and repo key.

fn absolute_path_key_in_selected_project( state: &McpProjectState, path: &Path, ) -> Result<Option<String>, CliError>

Return a selected-project repository key for an absolute path inside the active root.

fn normalized_optional_path(path: Option<String>) -> Option<String>

Normalize optional project/root path text from MCP payloads.

fn project_state_from_root(root: &Path) -> Result<McpProjectState, CliError>

Build ProjectAtlas state for one project root.

fn project_state_from_root_with_config_validation( root: &Path, validation: McpConfigValidation, ) -> Result<McpProjectState, CliError>

Build project state while controlling when configuration content is validated.

fn project_state_from_nearest_indexed_path( path: &Path, ) -> Result<Option<McpProjectState>, CliError>

Build project state from the nearest indexed ancestor of an addressed path.

fn project_state_from_nearest_indexed_path_with_config_validation( path: &Path, validation: McpConfigValidation, ) -> Result<Option<McpProjectState>, CliError>

Build nearest canonical project state under one config-validation policy.

fn project_state_from_nearest_lexical_indexed_path( path: &Path, ) -> Result<Option<McpProjectState>, CliError>

Build project state from the nearest lexical indexed ancestor of an addressed path.

fn project_state_from_nearest_lexical_indexed_path_with_config_validation( path: &Path, validation: McpConfigValidation, ) -> Result<Option<McpProjectState>, CliError>

Build nearest lexical project state under one config-validation policy.

fn indexed_root_from_candidate(candidate: &Path) -> Option<McpIndexedRoot>

Return a role-typed indexed root when a candidate folder has a matching DB.

fn indexed_root_from_lexical_candidate( candidate: &Path, ) -> Option<McpIndexedRoot>

Return an indexed lexical root without treating symlinked descendants as the lexical owner.

fn lexically_normalized_absolute_path(path: &Path) -> PathBuf

Return a normalized absolute path without resolving symlinks or junctions.

fn path_has_symlink_component(path: &Path) -> bool

Return whether a path contains a symlink component in its lexical ancestry.

fn metadata_is_symlink_or_reparse_point(metadata: &Metadata) -> bool

Return whether metadata represents a symlink or Windows reparse point.

fn reject_ambiguous_nearest_project_path( path: &Path, lexical_state: Option<&McpProjectState>, canonical_state: Option<&McpProjectState>, canonical_path: &McpAbsolutePath, ) -> Result<(), CliError>

Reject nearest-project routing when lexical and canonical roots disagree.

fn ambiguous_nearest_project_path_error( path: &Path, lexical_state: Option<&McpProjectState>, canonical_state: Option<&McpProjectState>, ) -> CliError

Build a clear MCP error for ambiguous symlink or junction routing.

fn nearest_indexed_db_matches_root( db_path: &Path, root: &CanonicalProjectRoot, ) -> bool

Return whether nearest routing can safely associate one DB with a live root.

fn nearest_existing_roots_match( persisted_root: &CanonicalProjectRoot, selected_root: &CanonicalProjectRoot, ) -> bool

Re-resolve both existing roots before nearest-routing comparison.

fn projectatlas_db_path(root: &Path) -> PathBuf

Return the standard ProjectAtlas DB path for one project root.

fn projectatlas_nested_config_path(root: &Path) -> PathBuf

Return the standard nested ProjectAtlas config path for one project root.

fn projectatlas_flat_config_path(root: &Path) -> PathBuf

Return the flat ProjectAtlas config path for one project root.

fn config_path_for_project_root( root: &Path, validation: McpConfigValidation, ) -> Result<Option<PathBuf>, CliError>

Find a project-local config and optionally reject one pointing at another root.

fn validate_project_config_root( root: &Path, config_path: &Path, ) -> Result<(), CliError>

Ensure a selected project’s config cannot redirect the MCP root.

fn config_matches_project_root(root: &Path, config_path: &Path) -> bool

Return whether a startup config belongs to the selected root.

fn render_project_state(state: &McpProjectState) -> Result<String, CliError>

Render active project state for agents.

fn project_state_payload(state: &McpProjectState) -> McpProjectStatePayload

Build selected-project payload fields.

fn with_selected_project_audit( state: &McpProjectState, routed_project: bool, toon: String, ) -> Result<String, CliError>

Prefix routed cross-project read payloads with selected root/DB metadata.

fn with_selected_project_audit_controlled( state: &McpProjectState, routed_project: bool, toon: String, control: &IndexWorkControl, ) -> Result<String, CliError>

Prefix one controlled analysis payload with selected root/DB metadata.

fn path_or_project_root( state: &McpProjectState, path: Option<String>, ) -> Result<PathBuf, CliError>

Return a path parameter or the selected project root.

fn preflight_purpose_path( state: &McpProjectState, path: &str, ) -> Result<String, CliError>

Reject invalid purpose targets before admission can supersede another source witness.

fn require_indexed_purpose_path( store: &AtlasStore, node_key: &str, ) -> Result<(), CliError>

Require a purpose target in the captured index, including inside its write transaction.

fn selected_project_path_error(message: impl Display) -> CliError

Add selected-project guidance to repository-relative path errors.

fn query_or_empty(query: Option<String>) -> String

Return a query parameter with a stable default.

fn encode_serialized_payload<T>(payload: T) -> Result<String, CliError>

where T: Serialize,

Encode one serializable payload as agent-readable TOON text.

fn encode_named_payload<T>(key: &str, payload: &T) -> Result<String, CliError>

where T: Serialize,

Encode a dynamic top-level payload key without relying on json! key syntax.

fn encode_two_named_payloads<T, U>( first_key: &str, first_payload: &T, second_key: &str, second_payload: &U, ) -> Result<String, CliError>

where T: Serialize, U: Serialize,

Encode two dynamic top-level payload keys without relying on json! key syntax.

fn encode_error_payload(error: &CliError) -> String

Encode an MCP error as a structured agent-readable payload.

fn as_mcp_text(result: Result<String, CliError>) -> McpToolTextResult

Convert a command result into an agent-readable TOON MCP text payload.

impl ProjectAtlasMcpServer

pub fn atlas_set_project_path_tool_attr() -> Tool

Generated tool metadata function for atlas_set_project_path

fn atlas_set_project_path( &self, Parameters: Parameters<AtlasSetProjectPathParams>, ) -> McpToolTextResult

Select the active project root for subsequent MCP calls.

pub fn atlas_worktree_list_tool_attr() -> Tool

Generated tool metadata function for atlas_worktree_list

fn atlas_worktree_list( &self, Parameters: Parameters<AtlasWorktreeListParams>, ) -> McpToolTextResult

Return bounded structural and ProjectAtlas worktree state without mutation.

pub fn atlas_worktree_add_tool_attr() -> Tool

Generated tool metadata function for atlas_worktree_add

fn atlas_worktree_add( &self, Parameters: Parameters<AtlasWorktreeAddParams>, ) -> McpToolTextResult

Register one active structural worktree in the immutable control atlas.

pub fn atlas_worktree_remove_tool_attr() -> Tool

Generated tool metadata function for atlas_worktree_remove

fn atlas_worktree_remove( &self, Parameters: Parameters<AtlasWorktreeRemoveParams>, ) -> McpToolTextResult

Final-sync and retire one ProjectAtlas alias without touching Git or files.

pub fn atlas_init_tool_attr() -> Tool

Generated tool metadata function for atlas_init

fn atlas_init( &self, Parameters: Parameters<AtlasInitParams>, ) -> McpToolTextResult

Initialize a ProjectAtlas project-local config surface.

pub fn atlas_map_tool_attr() -> Tool

Generated tool metadata function for atlas_map

fn atlas_map(&self, Parameters: Parameters<AtlasMapParams>) -> McpToolTextResult

Write an explicit compatibility map export.

pub fn atlas_root_tool_attr() -> Tool

Generated tool metadata function for atlas_root

fn atlas_root( &self, Parameters: Parameters<AtlasRootParams>, ) -> McpToolTextResult

Return root/DB/config diagnostics.

pub fn atlas_root_set_tool_attr() -> Tool

Generated tool metadata function for atlas_root_set

fn atlas_root_set( &self, Parameters: Parameters<AtlasRootSetParams>, ) -> McpToolTextResult

Bind, move, or detach a project root and then make it active.

pub fn atlas_config_tool_attr() -> Tool

Generated tool metadata function for atlas_config

fn atlas_config( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Return the effective ProjectAtlas config.

pub fn atlas_ignore_list_tool_attr() -> Tool

Generated tool metadata function for atlas_ignore_list

fn atlas_ignore_list( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Return the effective ProjectAtlas ignore policy.

pub fn atlas_ignore_init_gitignore_tool_attr() -> Tool

Generated tool metadata function for atlas_ignore_init_gitignore

fn atlas_ignore_init_gitignore( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Create a project-root .gitignore when it is absent.

pub fn atlas_ignore_add_tool_attr() -> Tool

Generated tool metadata function for atlas_ignore_add

fn atlas_ignore_add( &self, Parameters: Parameters<AtlasIgnoreMutationParams>, ) -> McpToolTextResult

Add a manual ProjectAtlas ignore entry.

pub fn atlas_ignore_remove_tool_attr() -> Tool

Generated tool metadata function for atlas_ignore_remove

fn atlas_ignore_remove( &self, Parameters: Parameters<AtlasIgnoreMutationParams>, ) -> McpToolTextResult

Remove a manual ProjectAtlas ignore entry.

pub fn atlas_scan_tool_attr() -> Tool

Generated tool metadata function for atlas_scan

fn atlas_scan( &self, Parameters: Parameters<AtlasScanParams>, ) -> McpToolTextResult

Scan a repository, import purpose metadata, rebuild symbols, and return an overview.

fn atlas_overview_response( &self, params: AtlasProjectParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Render one verified overview response with optional request cancellation.

pub fn atlas_overview_tool_attr() -> Tool

Generated tool metadata function for atlas_overview

fn atlas_overview( &self, Parameters: Parameters<AtlasProjectParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return the indexed repository overview.

pub fn atlas_folders_tool_attr() -> Tool

Generated tool metadata function for atlas_folders

fn atlas_folders( &self, Parameters: Parameters<AtlasQueryParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Rank folders before an agent chooses a work area.

fn atlas_folders_response( &self, params: AtlasQueryParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Build the folders response with optional request telemetry context.

pub fn atlas_files_tool_attr() -> Tool

Generated tool metadata function for atlas_files

fn atlas_files( &self, Parameters: Parameters<AtlasFilesParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Rank files after an agent has chosen a folder or query.

fn atlas_files_response( &self, params: AtlasFilesParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Build the files response with optional request telemetry context.

pub fn atlas_next_tool_attr() -> Tool

Generated tool metadata function for atlas_next

fn atlas_next( &self, Parameters: Parameters<AtlasNextParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Recommend the next indexed folders, files, and inspection commands.

pub fn atlas_outline_tool_attr() -> Tool

Generated tool metadata function for atlas_outline

fn atlas_outline( &self, Parameters: Parameters<AtlasOutlineParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Build a compact file outline.

fn atlas_file_summary_response( &self, params: &AtlasFileSummaryParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Render one verified structured file-summary response.

pub fn atlas_file_summary_tool_attr() -> Tool

Generated tool metadata function for atlas_file_summary

fn atlas_file_summary( &self, Parameters: Parameters<AtlasFileSummaryParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return deterministic structured file intelligence from the deep index.

pub fn atlas_search_tool_attr() -> Tool

Generated tool metadata function for atlas_search

fn atlas_search( &self, Parameters: Parameters<AtlasSearchParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Search selected indexed files with optional context lines.

pub fn atlas_slice_tool_attr() -> Tool

Generated tool metadata function for atlas_slice

fn atlas_slice( &self, Parameters: Parameters<AtlasSliceParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return an exact line or symbol slice from a selected file.

pub fn atlas_symbols_build_tool_attr() -> Tool

Generated tool metadata function for atlas_symbols_build

fn atlas_symbols_build( &self, Parameters: Parameters<AtlasScanParams>, ) -> McpToolTextResult

Rebuild symbol graphs for indexed files.

fn atlas_symbols_response( &self, params: &AtlasSymbolsParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Render one verified symbol-list response.

pub fn atlas_symbols_tool_attr() -> Tool

Generated tool metadata function for atlas_symbols

fn atlas_symbols( &self, Parameters: Parameters<AtlasSymbolsParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

List indexed symbols.

fn detailed_symbol_relations_response( state: &McpProjectState, routed_project: bool, file: &str, params: &AtlasSymbolRelationsParams, content_selection: ContentSelection, analysis: bool, stores: SymbolRelationStores<'_>, control: &IndexWorkControl, ) -> Result<(String, Option<McpUsageIntent>), CliError>

Render the shared detailed/analysis contract through one selected store set.

fn atlas_symbol_relations_response( &self, params: &AtlasSymbolRelationsParams, context: Option<RequestContext<RoleServer>>, ) -> McpToolTextResult

Render one verified legacy or detailed symbol-relation response.

pub fn atlas_symbol_relations_tool_attr() -> Tool

Generated tool metadata function for atlas_symbol_relations

fn atlas_symbol_relations( &self, Parameters: Parameters<AtlasSymbolRelationsParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

List indexed symbol relations.

pub fn atlas_health_tool_attr() -> Tool

Generated tool metadata function for atlas_health

fn atlas_health( &self, Parameters: Parameters<AtlasHealthParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return structural health findings.

pub fn atlas_health_resolve_tool_attr() -> Tool

Generated tool metadata function for atlas_health_resolve

fn atlas_health_resolve( &self, Parameters: Parameters<AtlasHealthResolveParams>, ) -> McpToolTextResult

Mark an intentional deterministic health finding as resolved.

pub fn atlas_lint_tool_attr() -> Tool

Generated tool metadata function for atlas_lint

fn atlas_lint( &self, Parameters: Parameters<AtlasLintParams>, ) -> McpToolTextResult

Run ProjectAtlas lint checks without terminating the MCP transport.

pub fn atlas_token_report_tool_attr() -> Tool

Generated tool metadata function for atlas_token_report

fn atlas_token_report( &self, Parameters: Parameters<AtlasTokenParams>, ) -> McpToolTextResult

Return token savings telemetry.

pub fn atlas_parity_report_tool_attr() -> Tool

Generated tool metadata function for atlas_parity_report

fn atlas_parity_report( &self, Parameters: Parameters<AtlasParityParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return repository-intelligence parity readiness.

pub fn atlas_settings_tool_attr() -> Tool

Generated tool metadata function for atlas_settings

fn atlas_settings( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Return local settings and cache/index locations.

pub fn atlas_watch_status_tool_attr() -> Tool

Generated tool metadata function for atlas_watch_status

fn atlas_watch_status( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Return watcher availability and operating mode.

pub fn atlas_watch_once_tool_attr() -> Tool

Generated tool metadata function for atlas_watch_once

fn atlas_watch_once( &self, Parameters: Parameters<AtlasWatchOnceParams>, ) -> McpToolTextResult

Run one incremental refresh pass.

pub fn atlas_strip_legacy_purpose_tool_attr() -> Tool

Generated tool metadata function for atlas_strip_legacy_purpose

fn atlas_strip_legacy_purpose( &self, Parameters: Parameters<AtlasStripLegacyParams>, ) -> McpToolTextResult

Preview or remove legacy .purpose files.

pub fn atlas_reset_index_tool_attr() -> Tool

Generated tool metadata function for atlas_reset_index

fn atlas_reset_index( &self, Parameters: Parameters<AtlasResetIndexParams>, ) -> McpToolTextResult

Preview or remove local runtime index/cache files.

pub fn atlas_mcp_config_tool_attr() -> Tool

Generated tool metadata function for atlas_mcp_config

fn atlas_mcp_config( &self, Parameters: Parameters<AtlasMcpConfigParams>, ) -> McpToolTextResult

Generate a project-local MCP config document.

pub fn atlas_runtime_info_tool_attr() -> Tool

Generated tool metadata function for atlas_runtime_info

fn atlas_runtime_info( &self, Parameters: Parameters<AtlasProjectParams>, ) -> McpToolTextResult

Return runtime identity and compiled MCP tool surface.

pub fn atlas_session_brief_tool_attr() -> Tool

Generated tool metadata function for atlas_session_brief

fn atlas_session_brief( &self, Parameters: Parameters<AtlasSessionBriefParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return a compact startup brief for agents.

pub fn atlas_task_status_tool_attr() -> Tool

Generated tool metadata function for atlas_task_status

fn atlas_task_status( &self, Parameters: Parameters<AtlasTaskParams>, ) -> McpToolTextResult

Return typed status for one MCP task-progress record.

pub fn atlas_task_cancel_tool_attr() -> Tool

Generated tool metadata function for atlas_task_cancel

fn atlas_task_cancel( &self, Parameters: Parameters<AtlasTaskParams>, ) -> McpToolTextResult

Request cancellation for one MCP task-progress record.

pub fn atlas_purpose_queue_tool_attr() -> Tool

Generated tool metadata function for atlas_purpose_queue

fn atlas_purpose_queue( &self, Parameters: Parameters<AtlasPurposeQueueParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Return a bounded purpose curation queue.

pub fn atlas_purpose_set_tool_attr() -> Tool

Generated tool metadata function for atlas_purpose_set

fn atlas_purpose_set( &self, Parameters: Parameters<AtlasPurposeSetParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Set an agent-approved purpose in the durable index.

pub fn atlas_purpose_review_tool_attr() -> Tool

Generated tool metadata function for atlas_purpose_review

fn atlas_purpose_review( &self, Parameters: Parameters<AtlasPurposeReviewParams>, context: RequestContext<RoleServer>, ) -> McpToolTextResult

Batch-review existing purpose records through the MCP surface.

fn tool_router() -> ToolRouter<Self>

Trait Implementations

impl Clone for ProjectAtlasMcpServer

fn clone(&self) -> ProjectAtlasMcpServer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProjectAtlasMcpServer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ServerHandler for ProjectAtlasMcpServer

fn get_info(&self) -> ServerInfo

async fn call_tool( &self, request: CallToolRequestParams, context: RequestContext<RoleServer>, ) -> Result<CallToolResponse, ErrorData>

Handle a tools/call request from a client.

async fn list_tools( &self, _request: Option<PaginatedRequestParams>, context: RequestContext<RoleServer>, ) -> Result<ListToolsResult, ErrorData>

fn get_tool(&self, name: &str) -> Option<Tool>

Get a tool definition by name.

fn ping( &self, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

fn initialize( &self, request: InitializeRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<InitializeResult, ErrorData>> + MaybeSendFuture

fn supported_protocol_versions(&self) -> Cow<'static, [ProtocolVersion]>

Return the protocol versions supported by this server.

fn discover( &self, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<DiscoverResult, ErrorData>> + MaybeSendFuture

Return this server’s discovery information.

fn complete( &self, request: CompleteRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CompleteResult, ErrorData>> + MaybeSendFuture

fn set_level( &self, request: SetLevelRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

fn get_prompt( &self, request: GetPromptRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<GetPromptResponse, ErrorData>> + MaybeSendFuture

fn list_prompts( &self, request: Option<PaginatedRequestParams>, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<ListPromptsResult, ErrorData>> + MaybeSendFuture

fn list_resources( &self, request: Option<PaginatedRequestParams>, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<ListResourcesResult, ErrorData>> + MaybeSendFuture

fn list_resource_templates( &self, request: Option<PaginatedRequestParams>, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<ListResourceTemplatesResult, ErrorData>> + MaybeSendFuture

fn read_resource( &self, request: ReadResourceRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<ReadResourceResponse, ErrorData>> + MaybeSendFuture

fn accepted_subscription_filter( &self, requested: &SubscriptionFilter, ) -> Option<SubscriptionFilter>

Return the subset of a requested notification filter this server accepts.

fn listen( &self, context: SubscriptionContext, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

Run one established subscription until it is cancelled or closed gracefully.

fn subscribe( &self, request: SubscribeRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

👎Deprecated:

resources/subscribe is legacy-only; implement accepted_subscription_filter and listen for protocol version 2026-07-28

fn unsubscribe( &self, request: UnsubscribeRequestParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

👎Deprecated:

resources/unsubscribe is legacy-only; subscriptions/listen is cancelled through its request lifecycle

fn on_custom_request( &self, request: CustomRequest, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<CustomResult, ErrorData>> + MaybeSendFuture

fn on_cancelled( &self, notification: CancelledNotificationParam, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_progress( &self, notification: ProgressNotificationParam, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_initialized( &self, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_roots_list_changed( &self, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_custom_notification( &self, notification: CustomNotification, context: NotificationContext<RoleServer>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn get_task( &self, request: GetTaskParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<GetTaskResult, ErrorData>> + MaybeSendFuture

SEP-2663 tasks/get: return the current [DetailedTask] state.

fn update_task( &self, request: UpdateTaskParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

SEP-2663 tasks/update: accept responses to outstanding in-task input requests. Returns an empty acknowledgement on success.

fn cancel_task( &self, request: CancelTaskParams, context: RequestContext<RoleServer>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

SEP-2663 tasks/cancel: cooperative cancellation. Returns an empty acknowledgement; the task’s observable status may lag.