From v0.1 to v0.5: How Semantiq Evolved Into a Production-Ready MCP Server

In just 4 weeks, Semantiq went from a proof-of-concept MCP server with 9 languages and basic FTS5 search to a production-ready tool with ONNX-powered semantic search, 19 language support, adaptive ML thresholds, and multiple security hardening passes. Here's the full story.

The Beginning: v0.1.0 — A Proof of Concept#

On January 17, 2026, the first version of Semantiq shipped. It was simple: an MCP server with 4 tools (search, find_refs, deps, explain), support for 9 languages via tree-sitter, and a SQLite backend with FTS5 search.

1# The very first Semantiq experience
2npm install -g semantiq-mcp
3semantiq index .
4semantiq search "authentication handler"

The core idea was already there — give AI coding assistants semantic understanding of codebases through the MCP protocol. But the implementation was basic: text-based search with no real semantic understanding.

Within the same day, three more releases followed rapidly:

• v0.1.1 fixed npm documentation
• v0.1.2 added auto-indexing with file watching — no more manual re-indexing
• v0.1.3 introduced the semantiq init command for one-step Claude Code setup

The pattern was set: ship fast, iterate faster.

The Semantic Search Revolution: v0.2.x#

v0.2.1 — The Security Wake-Up Call#

Before adding features, the team addressed critical foundation issues. v0.2.1 was a quality release: SQL injection prevention via LIKE escaping, UTF-8 safety in tree-sitter extraction, an N+1 query fix that collapsed 4 database queries into 1, and proper mutex error handling.

This early focus on security would become a recurring theme.

v0.2.3 — ONNX Embeddings Change Everything#

This was a turning-point release. Semantiq integrated ONNX embedding models for true semantic search. Instead of just matching text, Semantiq now generated vector embeddings for code chunks and used cosine similarity to find semantically related code.

This made a big practical difference. Before v0.2.3, searching for "authentication handler" would only find code containing those exact words. After v0.2.3, it could find verifyCredentials(), checkJWT(), and loginUser() — code that means the same thing but uses completely different terminology.

1# Before: text-only search
2semantiq search "auth"  # Only finds literal "auth" matches
3
4# After: semantic search
5semantiq search "user authentication flow"
6# Finds: verifyCredentials, checkJWT, loginUser, validateSession

The implementation used MiniLM-L6-v2, a compact embedding model that runs locally via ONNX Runtime. No cloud APIs, no data leaving the developer's machine.

Technical deep-dive: The embedding pipeline works in three stages:

1. Tokenization: Code chunks are tokenized using the model's vocabulary (30,522 tokens)
2. Inference: ONNX Runtime runs the transformer model, producing 384-dimensional vectors
3. Storage: Vectors are stored in SQLite using sqlite-vec for efficient similarity search

The choice of MiniLM-L6-v2 was deliberate: it's small enough (90MB) to download quickly and run on any machine, yet powerful enough to capture meaningful semantic relationships. Larger models like CodeBERT were considered but rejected due to deployment complexity and the requirement for GPU acceleration.

v0.2.4 — Fixing What ONNX Broke#

Real-world deployment exposed issues. The ONNX model download failed in async Tokio contexts (fixed by switching from reqwest::blocking to ureq). The download size limit was too small for the 90MB model. ONNX inference crashed due to missing token_type_ids input.

This release taught an important lesson: integrating ML models into a systems tool requires careful attention to runtime compatibility.

v0.2.6 — Smart Reindexation#

A developer pain point solved: when the parser logic changed between versions, users had to manually run semantiq index --force. v0.2.6 introduced a PARSER_VERSION constant that triggers automatic reindexation when it changes. Seamless upgrades, no user action required.

This version also improved TypeScript/JavaScript support by extracting const/let variable declarations.

v0.2.8 — The Big Security Pass#

This was the first major security hardening release:

• SHA-256 checksum verification for ONNX model downloads (TOFU model)
• Path traversal protection with canonicalization
• AST recursion limits (max depth 500) to prevent stack overflow attacks
• Memory exhaustion prevention via pagination for embedding queries
• Restrictive file permissions (0600 on Unix) for database and models
• Symlink handling to prevent escape from project root

Each fix addressed a real attack vector. The philosophy: a tool that handles source code must be trustworthy.

Growing Up: v0.3.x#

v0.3.0 — The Architecture Overhaul#

This was the biggest release yet. Three major changes:

1. sqlite-vec integration replaced the custom vector search with proper vector similarity search using 384-dimensional MiniLM-L6-v2 embeddings
2. Automatic initial indexing when the MCP server starts — no more manual semantiq index step
3. 6 new languages: HTML, JSON, YAML, TOML, Bash, and Elixir (bringing the total to 15)

Plus ripgrep integration for fast text search, creating the hybrid 4-strategy search engine that defines Semantiq today:

Technical deep-dive on hybrid search: The challenge was combining results from four fundamentally different search strategies. Each returns scores on different scales: cosine similarity (0-1), ripgrep relevance (arbitrary), FTS5 BM25 scores (log scale), and dependency distance (integers).

The solution was a normalized ranking system:

1. Each strategy returns its top-k results with raw scores
2. Scores are normalized to a 0-1 range using min-max normalization within each strategy
3. Results are merged, with duplicates resolved by keeping the highest score
4. Final ranking uses a weighted combination: semantic (0.4), lexical (0.3), symbol (0.2), dependency (0.1)

This weighting was tuned empirically on a benchmark of 200 real developer queries, optimizing for the metric "relevant result in top 3."

v0.3.1 — Cursor Support#

The init-cursor command brought first-class Cursor/VS Code support. It generates .cursor/mcp.json, creates Cursor rules files, sets up VS Code configuration, and handles .cursorignore. One command, full IDE integration.

v0.3.3 — Search Filtering#

Power users needed more control. v0.3.3 added min_score, file_type, and symbol_kind parameters to semantiq_search. Now you could say "find authentication-related functions in TypeScript files with at least 50% relevance":

semantiq search "authentication" --min-score 0.5 --file-type ts --symbol-kind function

v0.3.4 — Platform Parity#

macOS Intel support was restored by making ONNX optional. Intel Macs use a stub embedding model (semantic search disabled), but all other features work. No platform left behind.

Production Ready: v0.4.0 and v0.5.x#

v0.4.0 — Structured Logging & Testing#

The shift from development tool to production software. JSON logging throughout the codebase, comprehensive MCP test coverage, and CI/security workflows. The serve command now outputs structured JSON logs by default for integration with log aggregators.

v0.5.0 — Adaptive ML Thresholds#

The most technically complex release. Semantiq now automatically calibrates semantic search thresholds per programming language:

1. Bootstrap mode: collects 100% of distance observations until 500 samples
2. Production mode: switches to 10% sampling after bootstrap
3. Auto-calibration: uses p90/p10 percentiles to set optimal thresholds
4. Per-language tuning: Rust code has different embedding characteristics than Python — Semantiq adapts

This means search quality improves automatically as you use the tool. No manual tuning required.

Technical deep-dive on adaptive thresholds: Different programming languages produce different embedding distributions. Verbose languages like Java have more spread-out embeddings (higher average distances), while concise languages like Go have tighter clusters.

A fixed threshold (e.g., 0.35) works poorly across languages:

• Too strict for Java: misses relevant results
• Too loose for Go: returns too much noise

The adaptive system solves this:

1# For each language, maintain a reservoir sample of distances
2# Bootstrap: collect all distances until 500 samples
3# Production: reservoir sampling at 10% rate
4
5# Compute percentiles from the sample
6p10 = percentile(distances, 10)  # "definitely related" threshold
7p90 = percentile(distances, 90)  # "definitely unrelated" threshold
8
9# Use p10 as the high-confidence threshold
10# Use interpolation between p10 and p50 for the default threshold

The release also included a massive refactoring effort: store.rs (2,108 lines) was split into 8 modules, and engine.rs (1,049 lines) into 5 modules. This wasn't just code organization — it unlocked better testability and prepared the architecture for concurrent index operations in future releases.

v0.5.2 — Security Hardening Round 2#

The latest release focused entirely on security:

• ReDoS prevention: user input escaped with regex::escape()
• Dependency update: bytes crate patched for integer overflow (RUSTSEC-2026-0007)
• Sensitive file protection: text search walker now excludes .env, .git/
• Path traversal fixes: canonicalization in read_file_lines()
• Input validation: length limits, empty checks on all MCP handlers
• Query amplification prevention: expansion limited to 10 terms
• Error message sanitization: no internal paths leaked to clients

By the Numbers#

Lessons Learned#

Four weeks of rapid iteration taught the team lessons about building developer tools:

1. Security Cannot Be Bolted On#

The earliest releases focused on functionality. By v0.2.8, security became a dedicated focus with path traversal protection, SQL injection prevention, and checksum verification. In hindsight, integrating security from day one would have been more efficient than retrofitting.

Key insight: Any tool that handles source code and exposes network APIs needs threat modeling before the first release, not after.

2. ML in Systems Tools Is Hard#

Integrating ONNX embeddings revealed unexpected challenges:

• Async runtime conflicts (reqwest::blocking vs Tokio)
• Missing model inputs (token_type_ids)
• Model download reliability in CI/CD environments
• Platform-specific issues (macOS Intel vs ARM)

Key insight: ML integration requires extensive real-world testing. Lab environments miss platform diversity and edge cases.

3. User Feedback Shapes Architecture#

Features like automatic reindexation (v0.2.6), search filtering (v0.3.3), and adaptive thresholds (v0.5.0) all came from user feedback. The original design assumed developers would manually tune parameters — actual usage showed they wouldn't.

Key insight: Build instrumentation and feedback loops early. Assumptions about user behavior are usually wrong.

4. Refactoring Pays Off#

The v0.5.0 module split seemed like pure technical debt cleanup. Instead, it enabled:

• Faster testing cycles (isolated module tests)
• Easier contributions (smaller, focused files)
• Better documentation (module-level docs)
• Future parallelization (clear boundaries)

Key insight: Large refactors feel expensive but compound over time. Do them before the codebase becomes unmaintainable.

5. Hybrid Approaches Beat Pure Solutions#

Early versions tried to be "pure semantic search." Adding ripgrep for lexical search (v0.3.0) felt like admitting defeat. Instead, it made the tool genuinely useful — combining the strengths of different approaches beats any single strategy.

Key insight: Pragmatism over purity. Users want results, not elegant architecture diagrams.

6. MCP Is the Right Abstraction#

The decision to build on MCP (Model Context Protocol) was validated repeatedly. As new AI coding tools emerged, Semantiq worked with them automatically. No per-tool integrations needed, no vendor lock-in.

Key insight: Standards-based APIs age better than proprietary integrations.

What's Next: The v0.6+ Roadmap#

Semantiq is now a mature, production-ready MCP server. The roadmap continues:

Near-term (v0.6.x)#

More Languages and Formats

• Swift and Kotlin for mobile development
• Haskell and Scala for functional programming
• SQL and GraphQL for data layer
• Terraform, Pulumi, and CloudFormation for infrastructure-as-code

Search Improvements

• Cross-file semantic understanding (understanding that UserService in one file relates to UserController in another)
• Call graph analysis for tracing execution paths
• Type-aware search (finding all implementations of an interface)

Performance

• Parallel indexing using Rayon work-stealing
• Incremental embedding updates (only re-embed changed chunks)
• Memory-mapped vector storage for larger codebases

Medium-term (v0.7-0.8)#

Team Features

• Shared indexes for monorepos
• Cloud sync for distributed teams
• Collaborative annotations and bookmarks
• Index caching in CI/CD pipelines

Advanced Analysis

• Dead code detection via semantic coverage
• Pattern detection (anti-patterns, security smells)
• Automatic documentation generation from code semantics
• Code similarity detection across repositories

AI Model Improvements

• Support for code-specific embedding models (CodeBERT, StarCoder embeddings)
• Fine-tuning on user's codebase for better domain-specific results
• Multi-modal understanding (code + comments + documentation)

Long-term Vision#

Universal Code Understanding

• Cross-repository search (find similar implementations across GitHub)
• Historical semantic search (how did this concept evolve over time?)
• IDE-native integrations beyond MCP

Enterprise Features

• On-premise deployment options
• SSO and access control
• Audit logging and compliance
• Custom model training pipelines

The foundation is solid. Every release builds on the principles established from day one: speed (Rust), intelligence (ONNX embeddings), privacy (100% local), and universality (MCP protocol).

Get Involved#

Semantiq is open source and actively developed. Here's how to get involved:

Try it today — installation takes 30 seconds:

npm install -g semantiq-mcp
semantiq init

Contribute — the codebase is designed for contributions:

• Well-documented modules after the v0.5.0 refactor
• Comprehensive test suite
• Clear coding standards and review process

Give feedback — the best features come from users:

• GitHub Issues for bug reports and feature requests
• GitHub Discussions for questions and ideas
• Discord community for real-time conversation

Your AI assistant will thank you. And so will we.