Fw Context MCP

Run the full dependency audit. Read-only. Returns structured results. Returns the raw per-check dicts (``name``, ``status``, ``message``, ``fix_cmd``, ``instructions``, ``critical``) — NOT the formatted ``doctor`` table. Read ``status``/``fix_cmd``/``instructions`` per issue; ``status="skipped"`` means a prerequisite is missing. Args: project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: list[dict]: one dict per check, ``DepCheckResult`` fields via ``asdict``.

Check whether the LLM backend is running and the configured embedding/chat model is installed. Read-only: yes. No side effects. Call before smart_search, semantic_search, or explain_symbol (when on-demand fallback is expected — pre-computed analysis returns instantly without the LLM backend). Args: project_root: Project root. Auto-detected if omitted. Used to locate the project's LLM configuration. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: dict: {ollama_enabled (bool), status (str — "ok"|"disabled"| "not_configured"|"model_missing"|"embedding_unavailable"|"error"), ollama_running (bool), ollama_url (str), configured_model (str), num_ctx (int), installed_models (list[str]), configured_embed_model (str), embedding_installed (bool), message (str, on error/disabled), model_details (list[dict], when Ollama running), suggest_cloud (bool), vec_available (bool), vec_error (str, optional), debug_log (str, optional — only when debug logging is enabled)}

Configure LLM settings for the current project. Writes to ``<project>/.fw-context/local.toml`` ONLY (gitignored, per-developer). Does NOT modify the global config or the shared project ``config.toml``. After writing, tests the configuration by making a simple API call (skipped when LLM is disabled). IMPORTANT: When ``chat_api_base`` points to an external host, source code snippets in chat prompts will be sent to that endpoint. Ensure this complies with your organization's data security policies. Consider using local Ollama or an internal API proxy first. Args: project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. chat_api_base: Chat API URL (see description for format details). chat_api_key: Bearer token for cloud/proxy APIs. chat_api_format: Override auto-detection: "auto", "ollama", "openai". model: Chat model name. embed_model: Embedding model name (Ollama only). auto_pull: Whether to auto-pull models on 404. stream: Stream chat responses via SSE. True avoids reverse-proxy idle timeouts. Returns: dict: {status ("ok"|"error"), chat_api (dict — configured, endpoint, format, model), model (str), auto_pull (bool), stream (bool), test_latency_s (float, on success), test_response (str, on success), compliance_warning (str, when chat_api_base is external), message (str)}

MANDATORY FIRST CALL for C/C++ projects. Return metadata about the most recently indexed build configuration — check index health before using any other fw-context tools. Read-only, and it spawns no subprocess — the startup daemon thread and the file watcher own the background reindex. Act on ``status``: * ``"ready"`` — up to date. Continue. * ``"reindexing"`` — background reindex running; queries stay accurate. Continue. ``reindex_progress`` holds its last log line. * ``"reindex_needed"`` — schema mismatch, changed compile_commands.json, or a source file that compile_commands.json does not cover. Queries still work on existing data. Read ``reindex_reasons``: a missing source file needs ``fw-context index --build``, the other two need only ``fw-context index``. * ``"no_index"`` — initialized, never indexed. Run ``fw-context index``. * ``"not_initialized"`` — run ``fw-context init``. * ``"error"`` — DB corruption or access error. Use other tools. Three conditions set ``reindex_needed``: an outdated schema, a changed compile_commands.json, and a source file that is on disk but absent from compile_commands.json. The third one needs a build, because only the build system writes that file — a plain reindex has no translation unit for the file and skips it without a word. Modified source files are something else: they are handled per-query, and never set it. ``indexed_at`` and ``first_indexed_at`` are UTC; file mtimes are local time. Never compare the two directly — in UTC+2 a correctly indexed file looks 2 hours newer than ``indexed_at``. Call with ``fast=False`` to find modified files. ``analysis`` splits the LLM-analysis coverage into project and vendor symbols: * ``model`` — the model of the analysis, or None. One model only, even when several were used. * ``analyze_vendor`` — the value at index time, not the current config. * ``project`` / ``vendor`` — ``{analyzed, skipped, total}``. ``skipped`` = tried, but not analyzable (body larger than the model context, an unparseable answer, or a body that was not readable). * ``complete`` — no work left: every project symbol is analyzed or skipped. True exactly when ``reindex_reasons`` holds no "unanalyzed symbols" entry. Vendor symbols excluded by ``analyze_vendor=False`` never block it, thus ``vendor.total`` large with ``vendor.analyzed=0`` is expected, not a defect. Args: project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. fast: When True (default), the header check reuses the cached manifest hashes. Both modes run the per-file scan, thus ``modified_files_count`` is accurate either way — a tool that reported "ready" while the search tools warned about the same file gave the caller two readings and no way to choose. False recomputes the header hashes and costs several times more. Returns: dict: {config_hash, project_id, project_root, build_system, compile_commands, indexed_at (str — "YYYY-MM-DD HH:MM:SS" in UTC, the completion time of the last full index), symbol_count, file_count, reference_count, modified_files_count (int — files whose content no longer matches the index; counted in both modes), header_affected_tus (int — number of TUs with stale header dependencies), manifest_verification (str — "full" when manifest.json exists, "none" otherwise), analysis (dict — LLM-analysis coverage split by project/vendor: {model, analyze_vendor, project: {analyzed, skipped, total}, vendor: {analyzed, skipped, total}, complete}), description (str), first_indexed_at (str — UTC, same format as indexed_at), vendor_paths (list[str] — config index.vendor_paths), project_paths (list[str] — config index.project_paths), bg_reindex_running (bool), reindex_progress (str or None — last log line when reindex is running), schema_version (int — DB schema version), current_schema (int — code expects), status (str — "ready"|"reindexing"| "reindex_needed"|"no_index"|"not_initialized"|"error"), reindex_needed (bool — structural mismatch requiring a full reindex), reindex_reasons (list[str] — why reindex is needed, empty when False. One of them asks for `fw-context index --build` rather than a plain reindex: when the tree is on a different branch than the index, compile_commands.json belongs to the OLD branch and carries its file list and its compiler flags, so only a build regenerates it. Read the reason text — it names the command it needs), stale (bool — True when reindex_needed or header_affected_tus > 0), _warning (str, optional — when manifest verification is not "full"), vec_available (bool), vec_error (str, optional), index_message (str — human-readable summary of index state), multi (bool — True for a multi-variant project), variants (list[dict] — {name, description, board}), images (list[dict] — {name, description, dir, type}), variant_images (dict — variant name to its image names), active_variant (str or None — [build] default_variant), active_image (str or None — [build] default_image), entry_point (str — the `ENTRY()` of the linker script of the build that the other fields describe, empty when no script names one), memory (list[dict] — the `MEMORY` regions of that build: {name, attributes, origin, length, origin_value, length_value, file_path, line})} About ``memory``: ``origin`` and ``length`` hold the expression the script writes, thus they differ by platform — an mbed script writes `0xefe00` and a Zephyr script writes `((673792) - 0xe6)`. ``origin_value`` and ``length_value`` hold the number, and both are None for an expression that names a symbol, such as `ORIGIN(RAM) + LENGTH(RAM)`. The end of a region is ``origin_value + length_value``. ``memory`` and ``entry_point`` describe ONE build. For a multi-variant project they follow ``config_hash``, which is the build named by ``[build] default_variant``, and both are empty when the config names no default. Use ``list_variants`` for the map of every build. ``memory`` is empty for a build system that records no linker script. A PlatformIO project is the measured case: SCons writes no ninja file and no link command the index can read, and the map file never names the script. An empty list means "not recorded", never "no memory". ``defines`` (dict — the `-D` flags of that build) and ``defines_varying`` (int). ``defines`` holds only the names that EVERY translation unit of the build carries with the same value, so the tool never shows the defines of one file as the defines of the build. ``defines_varying`` counts the names left out, thus a name absent from ``defines`` is either not defined at all or not defined everywhere — measured on the Mbed project: 27 names in all 881 units, 59 in only some, where the three assembly files get a shorter set. This is the configuration the BUILD states, not every macro the preprocessor saw. The second is three orders of magnitude larger — 27800 distinct names on the STM32 project — and almost all of it comes from the headers and the compiler. A Zephyr build keeps its real configuration in ``autoconf.h`` (740 `CONFIG_*` names) and passes few `-D` flags, so ``defines`` says little there and a great deal on an mbed build, where it holds `APPLICATION_ADDR`, `APPLICATION_SIZE`, and `CMSIS_VECTAB_VIRTUAL`. For a project that is not initialized, the result holds only ``status``, ``project_root``, and ``index_message``. When no index exists, the result adds ``project_id``.

Return the complete project environment status in one call. Read-only. Aggregates five domains into a single call so the LLM can see everything at session start without extra round-trips: - ``deps`` — dependency audit (``run_full_check``), each entry with an optional ``action`` (``message`` + shell ``command``). ``status="skipped"`` means a prerequisite is missing (e.g. ``libclang-so`` skipped because ``libclang-python`` is absent) — not a failure. - ``build_system`` — detected build system, ``None`` when unknown. - ``compile_db`` — whether compile_commands.json exists and its entry count. Reported as ``{"exists": false, ...}`` before init (no config to resolve the path from, and loading one would create empty config files). - ``index`` — the FULL ``get_active_build()`` result, unchanged (its action lives in ``index_message``). - ``llm`` — LLM backend status with an optional ``action``. When the project is not initialized (``index.status == "not_initialized"``), only the config-independent dependency subset runs (checks that do not need a project config) — Ollama/model/db/build checks are skipped. Args: project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: dict: {init_status (str — "initialized" or "not_initialized"), deps (list[dict] — name, status, message, and an optional action), build_system (str or None), compile_db (dict — {exists (bool), path (str or None), entry_count (int or None — None before init, and when fw-context cannot read the file)}), index (dict — the full ``get_active_build`` result), llm (dict — {enabled, ollama_running, chat_model, embed_model}, plus ``ollama_enabled`` when the LLM check ran, plus an optional ``action``)}.

Return project metadata (name, type, root_path) for a project ID. Looks up the global project registry at ``~/.fw-context/projects.db``. Use this to identify a project from its UUID4 — find out what build system it uses, its name, and where it was last indexed. Read-only. No side effects. Args: project_id: Project ID (UUID4 hex) to look up. Returns: dict: {project_id, name, project_type, root_path, created_at, updated_at} or {"error": "..."} when the project_id is not registered. On failure the dict holds only ``error`` with the reason.