Hitmux Context Engine: semantic code search as an MCP server

The gap Hitmux Context Engine targets in agent workflows

An agent asked to change authentication code usually reaches for grep. That works when you know the identifier. It fails when the request is phrased as a question, when the relevant function is named something you would not have guessed, or when the answer lives in a design note rather than a source file. Hitmux Context Engine exists to answer that second class of query. It indexes a local directory into Milvus-compatible vector storage, then serves the index to MCP clients through focused tools for finding relevant code, docs, notes and config. The README lists Claude Code, OpenAI Codex CLI, OpenCode, Cursor and Windsurf as supported clients, so the intended user is someone already driving an agent through MCP who wants retrieval to be part of the agent's toolset rather than a separate search window. The project is TypeScript, MIT licensed, and published as three npm packages: the MCP server, a CLI alias, and a core indexing library. It is explicitly based on the core of zilliztech/claude-context, which matters for anyone who has already evaluated that project.

Indexing, embedding and retrieval: the mechanism in the repository

The pipeline has four visible stages. The core package walks a directory, splits files into chunks, embeds them through a configured provider, and writes the vectors to a Milvus-compatible store. The MCP server then exposes query tools over that store. Two design decisions stand out. First, configuration lives in conf files rather than environment variables: the README states that environment variables and `~/.hitmux-context-engine/.env` are not used for MCP product options, and that the resolution order is the global config, then a project-level config, then built-in defaults, with project values overriding global ones for fields that are present. Second, the search tools default to the whole index but can be narrowed to docs-only or code-only scope, which is a real distinction when a repository mixes prose and source. The repository layout shows `packages/core` for the indexing engine, `packages/mcp` for the server, plus `evaluation` and `benchmark` directories. The README does not publish retrieval quality numbers, so the benchmark directory is where you would look for the project's own measurements rather than taking any claim on faith.

Installing hce and running a first index

The published path is a global npm install followed by an interactive init that writes the runtime config. The CLI package is `@hitmux/hce`, and the README notes it starts the same server as the original `@hitmux/hitmux-context-engine-mcp` package.

npm install -g @hitmux/hce@latest
hce init

After init, edit `~/.hitmux-context-engine/config.conf` and fill in the provider key. Then verify the config and connectivity before touching an index:

hce doctor

The database note in the README is the part people skim past. For a local Milvus, set `milvusAddress = localhost:19530`. For a remote self-hosted instance, replace it with the reachable host and port and add `milvusToken` only if authentication is required. For Zilliz Cloud, sign up at the linked endpoint, use the cloud public endpoint, and set `milvusToken` to your Personal Key. The README states plainly that other database backends are not selectable from `config.conf`. Once the config checks out, build the first index from the repository root:

hce index .
hce status .

Then register the server with your client. For Claude Code the README gives `claude mcp add hitmux-context-engine -- hce`, and for Codex CLI, `codex mcp add hitmux-context-engine -- hce`. Open the client in the repository and ask it to check indexing status. From a shell, `hce search "query" . --limit 5 --scope all` runs the same retrieval without an agent in the loop, which is the fastest way to judge whether the index is any good. For a local source checkout, `./scripts/install-local-global.sh` builds the workspace and installs a user-level command; running it with `sudo` installs globally.

The Milvus requirement is the adoption decision

Most of the friction in this project comes from one constraint: it needs a Milvus-compatible vector database, either local, self-hosted remote, or Zilliz Cloud, and nothing else is selectable from the config file. If your team has no vector database and no appetite for running one, the install story stops at `hce doctor` and the value never materializes. A local Milvus on `localhost:19530` is the lowest-commitment route, but it is still a service to start, keep running and back up. There is also a staleness question the README does not resolve. It documents `hce status .` and `hce status . --refresh`, and lists `hce clear`, `hce repair`, `hce rm` and `hce index --force` for managing indexes and collections, but it does not describe an automatic watch mode or a documented rollback path for a bad index. In practice that means treating indexing as an explicit step: rebuild with `hce index .` when the tree changes enough to matter, and use `hce repair` when status looks wrong. Teams that expect the index to track edits silently will be disappointed. A second limitation is scope: this is retrieval for agents, not a code intelligence layer. It does not claim to resolve symbols, follow type hierarchies or perform static analysis, so questions that require understanding a call graph are outside what the tool provides.

How it differs from claude-context and plain grep

The README states the project is based on the core of zilliztech/claude-context, so the honest comparison is about what changed around that core rather than the retrieval idea itself. The visible difference is configuration surface. Hitmux Context Engine resolves settings from conf files with a global-then-project override order and explicitly excludes environment variables and `.env` from MCP product options, which suits teams that want a checked-in project config rather than per-machine environment setup. It also ships a standalone CLI with index, status, search, list, clear, repair and remove subcommands, so the same index can be exercised from a shell without an MCP client attached. Against grep the difference is categorical: grep matches bytes, and this matches meaning, which is why the README frames the use case as queries that are natural-language, filename-based, heading-based or identifier-heavy. The trade-off is operational. Grep has no services, no embedding provider, no key to configure and no index to keep fresh. If your queries are literal and your repository is small, adding a vector database to answer them is a poor trade.

Maintenance, releases and licence terms

The last push to the default branch was on 2026-08-04, and the most recent release in the list is v0.2.18 from the same day, preceded by v0.2.16 and v0.2.15 in July 2026. The repository is not archived. That is a recent record of activity, but the version numbers are still in the 0.2.x range, so treat the configuration keys and CLI surface as things that can move between releases. The configuration file is the main upgrade cost: because settings resolve from conf files with a project-level override, a key rename or a changed default lands in your repository rather than in a shell profile, and you will see it the next time `hce doctor` runs. The licence is MIT, which permits commercial use and modification; the repository also carries an acknowledgement that the project is based on zilliztech/claude-context, and anyone redistributing a modified build should read both licences rather than assuming one covers the other. Nothing here is legal advice.

Editorial conclusion

Adopt it if your team already runs Milvus or is willing to sign up for a Zilliz Cloud database, works in an MCP client such as Claude Code, Codex CLI, Cursor or Windsurf, and wants retrieval that handles natural-language and identifier-heavy queries rather than literal grep. Skip it if you cannot stand up a vector database, if you need a backend other than Milvus or Zilliz, or if plain text search already answers your questions. Before rolling it out, run hce doctor against the config you intend to ship, and confirm that an index built from the repository root returns sensible hits for a query you already know the answer to.

Frequently asked questions

Official sources

1. hitmux/hitmux-context-engine on GitHub
2. License: MIT
3. Project website
4. README
5. Releases