Non-Speculative by cryptekbits - MCP Server

non-speculative

Documentation-focused MCP server with semantic search and optional RAG answers. Run as an MCP STDIO server or an optional HTTP server. CLI-first, npm-ready.

Install

npm i -g @cryptek/non-speculative
# or
npx @cryptek/non-speculative --help

Quickstart

STDIO (MCP mode)

npx @cryptek/non-speculative --docs-path ./docs
# Use with Claude Code, Cline, or any MCP client

HTTP mode

npx @cryptek/non-speculative --http --port 9000 --docs-path ./docs

# Test HTTP
curl http://localhost:9000/tools

CLI Options

Flag	Description	Default
`--docs-path <path>`	Path to documentation directory	`$PROJECT_ROOT` or `cwd`
`--http`	Enable HTTP server mode	`false` (STDIO)
`--port <number>`	HTTP server port	`9000`
`--no-watch`	Disable file watching	Enabled by default
`--cache-ttl-ms <ms>`	Doc index cache TTL	`300000` (5 min)
`--milvus-uri <uri>`	Milvus server URI	`http://localhost:19530`
`--milvus-db <name>`	Milvus database name	`default`
`--milvus-collection <name>`	Collection name	`doc_chunks`
`--embed-model <model>`	Embedding model	`nomic-embed-text`
`--groq-model <model>`	Groq LLM model	`llama-3.3-70b-versatile`
`--no-rerank`	Disable reranking	Enabled by default
`--max-concurrency <n>`	Max concurrent operations	`10`

Environment Variables

export GROQ_API_KEY="your-groq-api-key"        # Required for RAG answers
export MILVUS_URI="http://localhost:19530"     # Optional
export MILVUS_TOKEN="your-token"               # If using Milvus Cloud
export PROJECT_ROOT="/path/to/docs"            # Fallback docs path

Troubleshooting

Milvus not available: falls back to lexical/semantic search; RAG features degrade gracefully.
File watcher not triggering: on WSL/Docker, use --no-watch and restart after changes.
Groq API key missing: RAG answers fall back to search-only results.

Compatibility

Node.js >= 18

Roadmap

In progress

Non‑Speculative CLI + OpenTUI Onboarding — interactive init wizard, dependency checks, .docignore setup, server spawn from TUI.
Semantic Membership Gate for Documentation — multi‑stage gating (BM25 → LSH → ANN) with future classifier.

Planned

Web UI chat & spec manager — chat with docs, upload/refine specs, manage project specs.
DSPy + GEPA integration — optimize retrieval quality/cost with programmatic pipelines.
Cost & performance metrics — latency/cost/recall tracking, dashboards and alerts.
Spec versioning system — spec history, diffs, rollbacks, and releases.

Contributing

We welcome contributions! This repository has branch protection enabled to maintain code quality:

Direct pushes to main are blocked - all changes must go through pull requests
PR reviews are required - at least 1 approval needed before merging
Status checks must pass - CI tests must succeed
Conversations must be resolved - all review comments must be addressed
Claude AI reviews - PRs automatically get reviewed by Claude for code quality, security, and best practices

How to contribute:

Fork this repository
Create a feature branch in your fork (git checkout -b feature/amazing-feature)
Make your changes and commit (git commit -m 'Add amazing feature')
Push to your fork (git push origin feature/amazing-feature)
Open a Pull Request from your fork to this repository
Wait for automated Claude AI review and human approval
Address any feedback and get your PR merged

For Maintainers

The repository uses GitHub Actions for automated PR reviews powered by Claude AI. To enable this:

Add an ANTHROPIC_API_KEY secret to the repository:
- Go to Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name: ANTHROPIC_API_KEY
- Value: Your Anthropic API key
- Click "Add secret"
The PR review workflow (.github/workflows/pr-review.yml) will automatically:
- Trigger on new PRs and updates
- Analyze code changes
- Post detailed reviews with suggestions
- Flag security concerns and best practices

License

MIT