feat(embeddings): add orcarouter embedding provider

[clementguarino06510-glitch]

Summary

Add OrcaRouter as a first-class embedding provider for the Docs MCP Server's vector search, completely parallel to the existing OpenAI provider wiring.

OrcaRouter is an OpenAI-compatible AI gateway built for both models and agents. Like OpenRouter, it exposes a provider/model namespace across many models — but it also combines adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance behind the same endpoint. Adding orcarouter as a first-class provider means this project's users can use that stack directly, without treating OrcaRouter as an anonymous custom OPENAI_API_BASE endpoint.

It also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.

What's wired up

The change mirrors the existing openai case in createEmbeddingModel one-for-one:

File	Change
src/store/embeddings/EmbeddingFactory.ts	Add "orcarouter" to the EmbeddingProvider union, its areCredentialsAvailable branch (checks ORCAROUTER_API_KEY), and a new case "orcarouter" that builds OpenAIEmbeddings against the OrcaRouter endpoint — same encodingFormat: "float" fix, batchSize, and timeout handling as the OpenAI path
src/store/embeddings/EmbeddingConfig.ts	Add "orcarouter" to the provider union used for parsing/telemetry
.env.example	Document ORCAROUTER_API_KEY and optional ORCAROUTER_API_BASE
docs/guides/embedding-models.md	Add the provider to the supported-options list, credentials table, and a dedicated example section
src/store/embeddings/EmbeddingFactory.test.ts	Unit tests: default endpoint, ORCAROUTER_API_BASE override, missing-credentials error
src/store/embeddings/EmbeddingConfig.test.ts	Add orcarouter to the valid-providers check

Because OrcaRouter exposes an OpenAI-compatible embeddings endpoint on the same https://api.orcarouter.ai/v1 base URL as its chat/agent gateway, the existing OpenAIEmbeddings SDK path applies directly — no new dependency, and the vector-dimension auto-detection already in place for OpenAI-compatible providers works unchanged. Model names follow the OrcaRouter catalog, e.g.:

ORCAROUTER_API_KEY="..." \
DOCS_MCP_EMBEDDING_MODEL="orcarouter:openai/text-embedding-3-small" \
npx @arabold/docs-mcp-server@latest

ORCAROUTER_API_BASE can override the endpoint if desired.

Verification

• npm run lint ✅ (Biome, clean)
• npm run typecheck ✅
• npx vitest run src/store/embeddings ✅ (59 tests pass, including the new OrcaRouter tests)
• Full npm test: the 12 failing tests (test/github-private-repo-e2e.test.ts timeouts, test/refresh-pipeline-e2e.test.ts network/Invalid URL errors) fail identically on the pristine main tree in this environment — pre-existing and unrelated to this change.
• Live L3 check against the real OrcaRouter API using createEmbeddingModel("orcarouter:openai/text-embedding-3-small", ...): returned a 1536-dimension non-zero vector via https://api.orcarouter.ai/v1/embeddings.

---

Discord: discord.gg/YEubt8enRA · X: https://x.com/OrcaRouter

I'm an engineer on the OrcaRouter team.

[arabold]

Thanks for putting this together, and for the thorough writeup.

However, besides the obvious merge conflicts we have now, I'm not going to merge this. OrcaRouter exposes a standard OpenAI-compatible embeddings API, and the openai provider already covers that case in full:

OPENAI_API_KEY="your-orcarouter-api-key" \
OPENAI_API_BASE="https://api.orcarouter.ai/v1" \
DOCS_MCP_EMBEDDING_MODEL="openai/text-embedding-3-small" \
npx @arabold/docs-mcp-server@latest

That works today with no code changes, and dimension detection resolves openai/text-embedding-3-small to 1536 without even needing a probe. A dedicated orcarouter: branch would be a copy of the openai branch plus a default base URL, so it doesn't unlock anything a user can't already do — and it's the same argument every OpenAI-compatible gateway can make, which isn't a set I want to maintain one branch at a time.

Happy to take a docs-only PR adding OrcaRouter to docs/guides/embedding-models.md as an OpenAI-compatible endpoint example, alongside the Ollama and LM Studio ones. That's the part that actually helps people find it.