Skip to content

fix(jac-gpt): don't crash startup when MCP tool categorization LLM call fails#666

Merged
udithishanka merged 1 commit into
mainfrom
fix/jac-gpt-mcp-cache-startup-crash
Jun 30, 2026
Merged

fix(jac-gpt): don't crash startup when MCP tool categorization LLM call fails#666
udithishanka merged 1 commit into
mainfrom
fix/jac-gpt-mcp-cache-startup-crash

Conversation

@udithishanka

Copy link
Copy Markdown
Collaborator

Problem

The jaseci test-pypi-build CI job (Run tests for jaseci) has been red on main since jaseci-labs/jaseci#7042, failing at "Wait for jac-gpt server to be ready" (example run). The jac-gpt server never binds its port and the wait step times out.

That job scaffolds jac-gpt from the published jacpack (generated from this jac-gpt-fullstack/) and runs jac start main.jac.

Root cause

services/jacServer.jac made a blocking by llm() call (categorized_mcp_tools) at module / glob-init time to categorize the MCP tools, gated on the MCP client having discovered tools:

glob mcp_tools_cache: dict[str, list[str]] =
    reorder_categorized_mcp_tools(categorized_mcp_tools(available_mcp_tools_descriptions))
    if available_mcp_tools_descriptions else { ... };

This call was dormant until #7042: jac-gpt has no jac-mcp dependency, so before the fold jac mcp was an unknown command, McpClient got 0 tools, available_mcp_tools_descriptions was empty, and the else branch ran (no LLM call). #7042 made jac mcp a built-in command, so the client now connects, discovers 19 tools, and the by llm() call fires at startup.

Two further problems made that call fragile:

  • it ran before load_dotenv() and before glob llm = Model(...), so it used the default model with credentials not yet loaded;
  • any LLM error (no key / unreachable, as in CI) aborted module load, taking down the whole server.

The "missing credentials" error is not jaseci dropping the key: the jac-gpt CI step has no real LLM key, and byllm reads the key from the environment at call time. This is a jac-gpt startup-ordering / resilience bug that #7042 merely exposed.

Fix

  • Load .env up front (own with entry) so credentials are available before any LLM call.
  • Move categorization into a build_mcp_tools_cache() helper wrapped in try/except that falls back to the empty cache. The MCP chat abilities already read it via .get(..., []), so an empty cache is safe and the feature degrades gracefully.
  • Initialize the cache after glob llm is configured, so the intended model is used when a key is present.

Net effect: the server always boots; tool categorization is best-effort and only runs when both MCP tools and a working LLM are available.

Verification

Reproduced and verified against a jac binary built at a red commit (f6aed53e, which includes #7042):

  • Before: by llm() at glob-init with no key -> AuthenticationError -> Error loading <module> (server never starts), matching the CI trace.
  • After: same conditions (no key / invalid key) -> failure is caught, cache falls back to empty, and the module finishes loading ("server booted").
  • jac check passes on the changed constructs; jac format parses the file cleanly.

Once merged to main, the Generate jac-gpt Jacpack workflow republishes the jacpack to jaseci-labs/jacpacks, which unblocks the jaseci CI job.

…ll fails

jac-gpt made a blocking `by llm()` call (categorized_mcp_tools) at glob-init
to categorize MCP tools. After jaseci-labs/jaseci#7042 folded `jac mcp` into
core, the MCP client now connects and discovers tools, activating this
previously dormant call. When the LLM is unreachable or no API key is set
(as in CI), the call raised and aborted module load, so the server never
bound its port and startup hung.

Build the cache defensively:
- Load .env up front so credentials are available before any LLM call.
- Wrap categorization in try/except and fall back to an empty cache; the MCP
  chat abilities already read it via .get(..., []), so empty is safe.
- Initialize the cache after `llm` is configured so the intended model is used.
@udithishanka udithishanka merged commit 49902f8 into main Jun 30, 2026
1 check failed
@udithishanka udithishanka deleted the fix/jac-gpt-mcp-cache-startup-crash branch June 30, 2026 11:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant