create-academic-research 0.1.14 → 0.1.16

package/README.md

@@ -128,6 +128,7 @@ npm run skills:remove -- source-ingestion
 npm run skills:uninstall -- source-ingestion
 npm run skills:update
 npm run mcp:list
+npm run mcp:modes
 npm run mcp:enabled
 npm run mcp:available
 npm run mcp:commands -- arxiv
@@ -150,13 +151,34 @@ For direct one-off invocation without the generated package scripts, use
 
 `academic-research update` is a dry-run by default. It reports managed project
 files that would change and writes them only with `--apply`.
+Generated projects intentionally keep `npm run update` on
+`create-academic-research@latest` so one command can preview migrations from an
+older scaffold. Other lifecycle scripts use the package version recorded in the
+project dev dependency for reproducibility.
+
+```bash
+npm run update
+npm run update -- --apply
+```
+
+Very old projects may still have a pinned `update` script. Use the latest
+generator directly in that case:
+
+```bash
+npm exec --yes --package=create-academic-research@latest -- academic-research update --root .
+npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply
+```
+
+Safe migrations are tracked in `.academic-research/managed-files.json`. The
+manifest stores non-secret checksums for generator-owned files. If a file was
+edited locally, update reports `skip` instead of overwriting it.
 
 `academic-research init` initializes an existing repository without overwriting
 existing files. It adds the research contract, merges lifecycle package scripts,
 and preserves existing README, `.gitignore`, and custom package scripts.
 
 `academic-research setup` is a non-destructive onboarding status command. It
-prints the active preset, agent, skill counts, enabled MCP records, and next
+prints the active preset, agent, skill counts, selected MCP records, and next
 commands without changing files.
 
 Skills are project-local by default.
@@ -175,17 +197,21 @@ MCP commands are split by side-effect:
 | Command | Meaning |
 |---|---|
 | `mcp list` | List known MCP servers with enabled/available status. |
+| `mcp modes` | Show which servers can run locally, use a hosted endpoint, use a custom endpoint, require a local app, or need manual setup. |
+| `mcp status` | Show friendly selected/setup/client/probe readiness and next action for each MCP server. Add `--verbose` for technical lifecycle fields. |
 | `mcp enabled` | List only enabled MCP server ids. |
 | `mcp available` | List the local MCP catalog. |
 | `mcp commands` | Print finite external install commands without running them. Runtime-only `uvx`/`npx` servers may have no install command. |
 | `mcp env` | Print required/recommended env vars, hosted endpoints, local prerequisites, and setup commands for selected servers. Use `--dotenv --all` to print dotenv content or `--write .env.example --all` to regenerate `.env.example`. |
-| `mcp enable` | Enable an MCP server in project records and generated snippets. |
+| `mcp enable` | Select an MCP server in project records and generated snippets. Use `--mode local`, `--mode remote`, or `--mode remote-custom --url <url>` where supported. |
 | `mcp disable` | Remove an MCP server from project records and generated snippets. |
+| `mcp setup` | Run or dry-run finite setup for manual-local integrations such as Overleaf. |
+| `mcp client add` / `mcp client remove` | Register or remove supported MCP client entries, currently Codex, without writing secrets into client config. |
 | `mcp install` | Run finite external tool install commands for selected MCP servers. It must not launch stdio MCP servers. |
 | `mcp uninstall` | Run the external uninstall command when one exists. |
 | `mcp smoke` | Print non-launching readiness diagnostics for enabled or selected MCP servers. |
 | `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. Pass `--env-file .env.local` to read explicit local secrets. |
-| `mcp probe` | Opt-in runtime check that starts selected MCP servers and performs a stdio JSON-RPC handshake. |
+| `mcp probe` | Opt-in runtime check. Local stdio servers get a JSON-RPC handshake; remote endpoints are reported as configured without a network probe. |
 
 ## Companion Skills
 
@@ -221,19 +247,36 @@ Zotero, Overleaf, Crossref, and fallback aggregators are useful, but they need
 API keys, local apps, manual setup, or source-policy review. Enable them with
 `npm run mcp:enable -- <server>` after reading
 `docs/agent/mcp-setup.md`, use `npm run mcp:env -- <server>` to see runtime
-prerequisites, then run `npm run mcp:doctor`.
-
-The MCP catalog distinguishes local runtime adapters from hosted endpoints and
-manual integrations. arXiv and DBLP are low-friction local `uvx` runtimes.
+prerequisites, then run `npm run mcp:modes`, `npm run mcp:status`, and
+`npm run mcp:doctor`.
+
+The MCP catalog uses plain modes by default:
+local means your machine runs the MCP server, remote means your client connects
+to an existing hosted endpoint, custom remote means you provide the endpoint,
+requires local app means another desktop/service app must be running, and
+manual setup means guided setup is required before client registration.
+arXiv and DBLP are low-friction local `uvx` runtimes.
 Semantic Scholar is useful for citation graphs but works best with
 `SEMANTIC_SCHOLAR_API_KEY`. OpenAlex requires `OPENALEX_API_KEY` for the
-selected local adapter; OpenAlex keys are free and include a free daily quota,
-but high-volume work should check current credit limits. PubMed is a
+selected local adapter, while OpenAlex and PubMed can also be selected in
+remote hosted mode or a custom remote endpoint. PubMed local mode is a
 biomedical-specific `npx` runtime and remains opt-in. Zotero needs the local
-Zotero desktop app and Zoty setup. Overleaf is manual and credentialed.
+Zotero desktop app and Zoty setup. Overleaf is a manual setup integration with
+a generated safe dotenv-loading wrapper after `mcp setup`.
 Crossref and broad paper-search aggregators are kept as fallback/manual entries
 until a project explicitly needs them.
 
+Codex automatic registration supports custom remote endpoints when the URL is
+stored in project config with `--url`. If the endpoint URL is kept private via
+`--url-env`, Codex automatic registration is not available because the Codex CLI
+currently has no `--url-env` option. Either re-enable with
+`--url <url>` if the endpoint URL may be stored in Codex config, or manually run
+`codex mcp add <server> --url "$MCP_URL_ENV_VAR"` from a shell where the env var
+is set.
+An explicit `--mode remote-custom` override is not enough by itself; smoke and
+probe report `missing-remote-url` until the project has either a stored URL or a
+URL env var configured.
+
 Generated projects include a committed `.env.example` with empty MCP variables
 and ignore filled `.env` or `.env.local` files. Regenerate the example with
 `npm run mcp:dotenv`. `mcp doctor`, `mcp smoke`, and `mcp probe` check the
@@ -245,11 +288,20 @@ live tools by themselves. Your MCP client must load the generated snippet, and
 the referenced commands must be available on your machine or runnable through
 `uvx`/`npx`. `mcp install` only runs finite setup commands such as the arXiv
 tool install; it deliberately does not launch stdio MCP servers.
+`mcp setup overleaf --mode local --env-file .env.local` creates a local wrapper
+that loads secrets at runtime and records non-secret facts in
+`docs/agent/capability-lock.json`.
+`configs/capabilities.yaml` records intended project capabilities. The
+capability lock records observed setup facts such as MCP setup/client/probe
+state and project-local skill install/update/remove actions. The lock is
+non-secret and should never contain API keys, tokens, cookies, or env values.
 Use `mcp smoke` for a non-launching readiness pass before wiring a client: it
 checks required env vars, manual/local-service status, and whether runtime
 commands are visible on `PATH`.
 Use `mcp probe` only when you intentionally want to start selected MCP server
-processes and verify a real stdio JSON-RPC handshake.
+processes and verify a real stdio JSON-RPC handshake. Remote MCP endpoints are
+not started locally; probe reports that the remote endpoint is configured and
+does not perform network-dependent checks.
 
 ## Validate This Package
 

package/dist/src/capabilities.d.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { type Runner } from "./runner.js";
-import { type McpToolCommandKey } from "./stack.js";
+import { type McpToolCommandKey, type ResolvedMcpServer } from "./stack.js";
 import { formatMcpDotenv, listMcpEnvironmentEntries } from "./mcp-env.js";
 import { type McpProbeResult as ProbeResult } from "./mcp-probe.js";
 export { formatMcpDotenv, listMcpEnvironmentEntries };
@@ -12,6 +12,14 @@ export interface CapabilityState {
     preset: string;
     scope: "project-local";
     mcp_servers: string[];
+    mcp_server_modes: Record<string, string>;
+    mcp_server_remote: Record<string, McpRemoteConfig>;
+}
+export interface McpRemoteConfig {
+    url?: string;
+    url_env?: string;
+    transport: "streamable-http";
+    bearer_token_env_var?: string;
 }
 export interface InitializeCapabilitiesOptions {
     preset?: string;
@@ -23,6 +31,12 @@ export interface CapabilityCommandResult {
     count?: number;
     skills?: string[];
     servers?: string[];
+    skipped?: McpSkippedTool[];
+}
+export interface McpSkippedTool {
+    server: string;
+    reason: string;
+    next?: string;
 }
 export interface InstalledSkill {
     name: string;
@@ -42,11 +56,111 @@ export interface McpProbeOptions {
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
     clientVersion?: string;
+    mode?: string;
 }
 export interface RenderedMcpSnippet {
     fileName: string;
     content: string;
 }
+export interface CapabilityLock {
+    version: number;
+    generator: {
+        name: "create-academic-research";
+        version?: string;
+        updated_at?: string;
+    };
+    mcp: Record<string, CapabilityLockMcpServer>;
+    skills: CapabilityLockSkills;
+}
+export interface CapabilityLockSkills {
+    preset?: string;
+    agent?: string;
+    explicit_skill_ids?: string[];
+    last_action?: "install" | "update" | "remove";
+    status?: "ready" | "updated" | "removed";
+    updated_at?: string;
+    sources: Record<string, CapabilityLockSkillSource>;
+    skills: Record<string, CapabilityLockSkillEntry>;
+}
+export interface CapabilityLockSkillSource {
+    source: string;
+    skill_ids?: string[];
+    action: "install" | "update" | "remove";
+    status: "ready" | "updated" | "removed";
+    updated_at?: string;
+}
+export interface CapabilityLockSkillEntry extends CapabilityLockSkillSource {
+    root?: string;
+    path?: string;
+}
+export interface CapabilityLockMcpServer {
+    selected_mode?: string;
+    connection_mode?: string;
+    setup?: {
+        status: "ready" | "planned" | "missing" | "skipped";
+        server_path?: string;
+        wrapper_path?: string;
+        env_file?: string;
+        updated_at?: string;
+    };
+    clients?: Record<string, {
+        status: "registered" | "removed" | "manual" | "unsupported";
+        updated_at?: string;
+    }>;
+    probe?: {
+        status: string;
+        detail: string;
+        updated_at?: string;
+    };
+}
+export interface McpLifecycleStatus {
+    servers: McpLifecycleServerStatus[];
+}
+export interface McpLifecycleServerStatus {
+    id: string;
+    selected: boolean;
+    mode: string;
+    mode_key: string;
+    connection_mode: string;
+    state: string;
+    env: "ok" | "missing-required" | "missing-recommended" | "n/a";
+    install: string;
+    snippet: "available" | "missing" | "none";
+    client: string;
+    probe: string;
+    next: string;
+}
+export interface McpLifecycleOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export interface McpSetupOptions {
+    mode?: string;
+    envFile?: string;
+    env?: NodeJS.ProcessEnv;
+    dryRun?: boolean;
+}
+export interface McpSetupResult {
+    ok: boolean;
+    server: string;
+    mode: string;
+    commands: string[];
+    created: string[];
+    warnings: string[];
+    errors: string[];
+    next: string[];
+}
+export interface McpClientOptions {
+    agent?: string;
+    mode?: string;
+    dryRun?: boolean;
+}
+export interface McpClientResult {
+    ok: boolean;
+    server: string;
+    agent: string;
+    command: string[];
+    instructions: string[];
+}
 interface SkillInstallOptions {
     agent?: string;
 }
@@ -63,12 +177,14 @@ export declare function removeSkills(root: string, skills: string[], runner?: Ru
 export declare function updateSkills(root: string, runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function enableMcpServers(root: string, servers: string[], options?: {
     agent?: string;
+    mode?: string;
+    remote?: Partial<McpRemoteConfig>;
 }): Promise<CapabilityCommandResult>;
 export declare function disableMcpServers(root: string, servers: string[], options?: {
     agent?: string;
 }): Promise<CapabilityCommandResult>;
-export declare function mcpToolCommands(servers: string[], key?: McpToolCommandKey): string[][];
-export declare function mcpToolCommandTexts(servers: string[], key?: McpToolCommandKey): string[];
+export declare function mcpToolCommands(servers: string[], key?: McpToolCommandKey, modes?: Record<string, string | undefined>): string[][];
+export declare function mcpToolCommandTexts(servers: string[], key?: McpToolCommandKey, modes?: Record<string, string | undefined>): string[];
 export declare function installMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function uninstallMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function doctorMcpServers(root: string, options?: McpDoctorOptions): Promise<McpDoctorResult>;
@@ -76,4 +192,10 @@ export declare function probeMcpServers(root: string, servers: string[], options
 export declare function renderMcpSnippet(state: CapabilityState): RenderedMcpSnippet;
 export declare function renderCapabilityProfile(state: CapabilityState): string;
 export declare function renderMcpSetup(state: CapabilityState): string;
+export declare function getMcpLifecycleStatus(root: string, options?: McpLifecycleOptions): Promise<McpLifecycleStatus>;
+export declare function readCapabilityLock(root: string): Promise<CapabilityLock>;
+export declare function setupMcpServer(root: string, serverName: string, options?: McpSetupOptions, runner?: Runner): Promise<McpSetupResult>;
+export declare function clientAddMcpServer(root: string, serverName: string, options?: McpClientOptions, runner?: Runner): Promise<McpClientResult>;
+export declare function clientRemoveMcpServer(root: string, serverName: string, options?: McpClientOptions, runner?: Runner): Promise<McpClientResult>;
+export declare function resolveMcpServerForState(state: CapabilityState, serverName: string, mode?: string): ResolvedMcpServer;
 export declare function assertKnownMcpServers(servers: string[]): void;