@agentic-conexus/mcp
Advanced tools
Context-aware semantic search MCP server for OpenCode and other MCP clients
Version: 0.0.5 (Phase 5 - Integration & Documentation)
Status: 🚧 Active Development
Go Version: 1.23.4
Conexus is an agentic context engine that transforms Large Language Models (LLMs) into expert engineering assistants. It provides a multi-agent system for analyzing codebases, with built-in validation, profiling, and workflow orchestration.
Option 1: NPM/Bunx (Recommended - Pre-built Binaries)
# Install globally with npm
npm install -g @agentic-conexus/mcp
# Or use with bunx (no installation needed)
bunx @agentic-conexus/mcp
# Or use with npx
npx @agentic-conexus/mcp
Note: Pre-built binaries are included for:
- macOS (Intel & Apple Silicon)
- Linux (amd64 & arm64)
- Windows (amd64)
Option 2: From Source (For Development)
# Clone the repository
git clone https://github.com/ferg-cod3s/conexus.git
cd conexus
# Requires Go 1.23.4+ - https://go.dev/dl/
# Build from source
go build -o conexus ./cmd/conexus
# Run tests
go test ./...
# Run the MCP server (stdio mode - default)
npx @agentic-conexus/mcp
# Run with environment variables
CONEXUS_DB_PATH=./data/db.sqlite CONEXUS_LOG_LEVEL=debug npx @agentic-conexus/mcp
# Run in HTTP mode (for testing)
CONEXUS_PORT=3000 npx @agentic-conexus/mcp
Conexus provides first-class support for the Model Context Protocol (MCP), enabling seamless integration with AI assistants like Claude Desktop and Cursor.
Option 1: NPM/Bunx (Recommended for MCP clients)
# Install globally with npm
npm install -g @ferg-cod3s/conexus
# Or use with bunx (no installation needed)
bunx @ferg-cod3s/conexus
Configure in your MCP client (OpenCode, Claude Desktop, etc.):
{
"mcpServers": {
"conexus": {
"command": "bunx",
"args": ["@ferg-cod3s/conexus"],
"env": {
"CONEXUS_DB_PATH": "/path/to/your/project/.conexus/db.sqlite"
}
}
}
}
Option 2: Go Install (For development)
# Install Conexus
go install github.com/ferg-cod3s/conexus/cmd/conexus@latest
# Start the MCP server (stdio mode by default)
conexus
# Or run in HTTP mode
CONEXUS_PORT=3000 conexus
Configure for stdio mode (recommended for MCP):
{
"mcpServers": {
"conexus": {
"command": "conexus",
"env": {
"CONEXUS_DB_PATH": "/path/to/your/project/.conexus/db.sqlite"
}
}
}
}
Test the integration:
In your MCP client (OpenCode, Claude Desktop, etc.):
You: "Search for HTTP handler functions in this codebase"
AI Assistant: [Uses context.search tool]
Found 5 HTTP handlers:
- HandleRequest in internal/server/handler.go:42-68
- HandleHealth in internal/server/health.go:15-22
...
Environment Variables:
CONEXUS_DB_PATH: Path to SQLite database (default: ~/.conexus/db.sqlite)CONEXUS_LOG_LEVEL: Log level: debug, info, warn, error (default: info)CONEXUS_PORT: Run in HTTP mode instead of stdio (for development)| Tool | Status | Description |
|---|---|---|
context.search | ✅ Fully Implemented | Search code with filters (type, language, file patterns) |
context.get_related_info | ✅ Fully Implemented | Get related files, functions, and context |
context.index_control | ⏳ Partial | Indexing operations (status available, reindex planned) |
context.connector_management | ⏳ Partial | Data source management (list available, CRUD planned) |
Code Understanding:
"Show me all database query functions"
"Find the authentication middleware implementation"
"What functions handle user registration?"
Bug Investigation:
"Search for error handling in the payment module"
"Find all functions that access the user database"
"Show panic or fatal calls in the codebase"
Feature Development:
"Locate API endpoint handlers"
"Find all struct definitions related to orders"
"Search for configuration loading functions"
For using Conexus with specific projects, you can configure it to work with your existing codebase structure:
Create a project-specific MCP configuration:
{
"mcpServers": {
"conexus-myproject": {
"command": "conexus",
"args": ["mcp", "--root", "/path/to/your/project"],
"env": {
"CONEXUS_LOG_LEVEL": "info",
"CONEXUS_CONFIG": "/path/to/your/project/conexus.yml"
}
}
}
}
Create a conexus.yml file in your project root:
# conexus.yml - Project-specific configuration
project:
name: "my-project"
description: "Web application backend"
# Codebase settings
codebase:
root: "."
include_patterns:
- "**/*.go"
- "**/*.js"
- "**/*.ts"
- "**/*.py"
exclude_patterns:
- "**/node_modules/**"
- "**/vendor/**"
- "**/dist/**"
- "**/.git/**"
# Search configuration
search:
max_results: 50
similarity_threshold: 0.7
enable_fts: true
# Indexing settings
indexing:
auto_reindex: true
reindex_interval: "1h"
chunk_size: 1000
For team environments, use Docker to ensure consistent configuration:
# docker-compose.conexus.yml
version: '3.8'
services:
conexus:
image: conexus:latest
container_name: conexus-myproject
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- ./:/workspace:ro
- ./data:/data
environment:
- CONEXUS_ROOT_PATH=/workspace
- CONEXUS_LOG_LEVEL=info
- CONEXUS_CONFIG=/workspace/conexus.yml
working_dir: /workspace
# Start for your project
docker-compose -f docker-compose.conexus.yml up -d
# Test the connection
curl http://localhost:3000/health
Node.js Project:
codebase:
include_patterns:
- "**/*.js"
- "**/*.ts"
- "**/*.json"
- "**/*.md"
exclude_patterns:
- "**/node_modules/**"
- "**/coverage/**"
- "**/dist/**"
Python Project:
codebase:
include_patterns:
- "**/*.py"
- "**/*.md"
- "**/requirements*.txt"
- "**/pyproject.toml"
exclude_patterns:
- "**/__pycache__/**"
- "**/venv/**"
- "**/env/**"
- "**/.pytest_cache/**"
Go Project:
codebase:
include_patterns:
- "**/*.go"
- "**/go.mod"
- "**/go.sum"
- "**/*.md"
exclude_patterns:
- "**/vendor/**"
Monorepo:
codebase:
include_patterns:
- "packages/**/*.ts"
- "packages/**/*.js"
- "apps/**/*.ts"
- "apps/**/*.js"
exclude_patterns:
- "**/node_modules/**"
- "**/dist/**"
- "**/build/**"
Create reusable templates for different project types:
{
"mcpServers": {
"conexus-nodejs": {
"command": "conexus",
"args": ["mcp", "--root", "$PROJECT_ROOT"],
"env": {
"CONEXUS_CONFIG": "$PROJECT_ROOT/.conexus/nodejs.yml"
}
},
"conexus-python": {
"command": "conexus",
"args": ["mcp", "--root", "$PROJECT_ROOT"],
"env": {
"CONEXUS_CONFIG": "$PROJECT_ROOT/.conexus/python.yml"
}
}
}
}
For production deployments, custom embedding providers, and advanced search optimization, see the MCP Integration Guide.
Topics covered:
┌─────────────────────────────────────────────────────┐
│ Orchestrator │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Intent │ │ Workflow │ │ State │ │
│ │ Parser │ │ Engine │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────▼─────┐ ┌────▼─────┐ ┌────▼─────┐
│ Locator │ │ Analyzer │ │ Future │
│ Agent │ │ Agent │ │ Agents │
└─────┬─────┘ └────┬─────┘ └──────────┘
│ │
└───────┬───────┘
│
┌─────────────▼─────────────┐
│ Validation Layer │
│ ┌──────────┐ ┌─────────┐ │
│ │ Evidence │ │ Schema │ │
│ │Validator │ │Validator│ │
│ └──────────┘ └─────────┘ │
└───────────────────────────┘
│
┌─────────────▼─────────────┐
│ Profiling Layer │
│ ┌──────────┐ ┌─────────┐ │
│ │Collector │ │Reporter │ │
│ └──────────┘ └─────────┘ │
└───────────────────────────┘
| Component | Description | Status |
|---|---|---|
| Orchestrator | Workflow engine, intent parsing, state management | ✅ Complete |
| Locator Agent | Find files/functions matching patterns | ✅ Complete |
| Analyzer Agent | Extract control flow and data dependencies | ✅ Complete |
| Evidence Validator | Verify 100% evidence backing | ✅ Complete |
| Schema Validator | Validate AGENT_OUTPUT_V1 format | ✅ Complete |
| Profiler | Performance metrics and reporting | ✅ Complete |
| Integration Framework | End-to-end testing harness | ✅ Complete |
Conexus has 53 integration tests covering real-world scenarios:
# Run all tests
go test ./...
# Run integration tests only
go test ./internal/testing/integration
# Run with verbose output
go test -v ./internal/testing/integration
# Run with coverage
go test -cover ./...
# Run specific test
go test -run TestLocatorAnalyzerIntegration ./internal/testing/integration
| Category | Tests | Coverage |
|---|---|---|
| Framework Tests | 13 | Core test infrastructure |
| Duration Tests | 7 | Performance regression detection |
| E2E Fixture Tests | 4 | Workflow execution with test fixtures |
| Advanced Workflows | 7 | Complex multi-step scenarios |
| Coordination Tests | 5 | Multi-agent communication |
| Real-World Tests | 5 | Actual Conexus source code analysis |
Conexus agents use environment variables for configuration:
# Enable verbose logging
export CONEXUS_LOG_LEVEL=debug
# Set profiling interval (ms)
export CONEXUS_PROFILE_INTERVAL=100
# Enable evidence validation
export CONEXUS_VALIDATE_EVIDENCE=true
# Set cache directory
export CONEXUS_CACHE_DIR=~/.cache/conexus
# Require 100% evidence backing (default: true)
export CONEXUS_REQUIRE_FULL_EVIDENCE=true
# Schema validation mode (strict|lenient)
export CONEXUS_SCHEMA_MODE=strict
# Max validation errors before failing
export CONEXUS_MAX_VALIDATION_ERRORS=10
All agents produce standardized output following the AGENT_OUTPUT_V1 schema:
{
"schema_version": "AGENT_OUTPUT_V1",
"task_description": "Locate all HTTP handler functions",
"result_summary": "Found 5 HTTP handlers in 3 files",
"confidence_score": 0.95,
"items": [
{
"type": "function",
"name": "HandleRequest",
"file_path": "/internal/server/handler.go",
"line_start": 42,
"line_end": 68,
"evidence_file_path": "/internal/server/handler.go",
"evidence_line_start": 42,
"evidence_line_end": 68,
"classification": "primary",
"explanation": "HTTP handler implementing request processing logic"
}
],
"files_examined": ["/internal/server/handler.go"],
"metadata": {
"agent_name": "locator",
"execution_time_ms": 45,
"timestamp": "2025-01-15T10:30:00Z"
}
}
Key Requirements:
See API Reference for complete schema documentation.
Conexus provides a powerful workflow integration system that combines validation, profiling, and quality gates into coordinated multi-agent workflows.
package main
import (
"context"
"github.com/ferg-cod3s/conexus/internal/orchestrator"
"github.com/ferg-cod3s/conexus/internal/process"
"github.com/ferg-cod3s/conexus/internal/tool"
"github.com/ferg-cod3s/conexus/internal/validation/evidence"
)
func main() {
// Create orchestrator with default configuration
config := orchestrator.OrchestratorConfig{
ProcessManager: process.NewManager(),
ToolExecutor: tool.NewExecutor(),
EvidenceValidator: evidence.NewValidator(false), // false = non-strict mode
QualityGates: orchestrator.DefaultQualityGates(),
EnableProfiling: true,
}
orch := orchestrator.NewWithConfig(config)
// Execute a workflow
ctx := context.Background()
result, err := orch.HandleRequest(ctx, "find all HTTP handlers", permissions)
if err != nil {
log.Fatal(err)
}
// Access results with profiling data
fmt.Printf("Completed in %v\n", result.Duration)
fmt.Printf("Evidence coverage: %.1f%%\n", result.Profile.EvidenceCoverage)
}
Conexus provides three quality gate configurations:
config := orchestrator.OrchestratorConfig{
QualityGates: orchestrator.DefaultQualityGates(),
}
config := orchestrator.OrchestratorConfig{
QualityGates: orchestrator.RelaxedQualityGates(),
}
config := orchestrator.OrchestratorConfig{
QualityGates: orchestrator.StrictQualityGates(),
}
config := orchestrator.OrchestratorConfig{
QualityGates: &orchestrator.QualityGateConfig{
RequireEvidenceBacking: true,
MinEvidenceCoverage: 95.0,
AllowUnbackedClaims: 2,
MaxExecutionTime: 3 * time.Minute,
MaxAgentExecutionTime: 30 * time.Second,
BlockOnValidationFailure: true,
BlockOnPerformanceFailure: false,
},
}
Enable automatic profiling to capture performance metrics:
config := orchestrator.OrchestratorConfig{
EnableProfiling: true,
}
result, _ := orch.ExecuteWorkflow(ctx, workflow, permissions)
// Access profiling data
profile := result.Profile
fmt.Printf("Total duration: %v\n", profile.TotalDuration)
fmt.Printf("Agent time: %v\n", profile.AgentExecutionTime)
fmt.Printf("Validation time: %v\n", profile.ValidationTime)
fmt.Printf("Profiling overhead: %.2f%%\n", profile.ProfilingOverheadPercent)
Evidence validation is automatically integrated:
// Strict mode - requires 100% evidence backing
validator := evidence.NewValidator(true)
// Non-strict mode - allows partial evidence
validator := evidence.NewValidator(false)
config := orchestrator.OrchestratorConfig{
EvidenceValidator: validator,
}
Generate comprehensive workflow reports:
result, _ := orch.ExecuteWorkflow(ctx, workflow, permissions)
// Generate workflow report
report := orchestrator.GenerateWorkflowReport(result)
fmt.Println(report.ExecutionSummary)
fmt.Println(report.ValidationReport)
fmt.Println(report.PerformanceReport)
Example report output:
=== Workflow Execution Report ===
Execution Summary:
Duration: 127ms
Agents Executed: 2
Status: ✅ Success
Validation Report:
Evidence Coverage: 100.0%
Backed Claims: 15
Unbacked Claims: 0
Status: ✅ Passed
Performance Report:
Agent Execution: 85ms (66.9%)
Validation: 12ms (9.4%)
Profiling Overhead: 1.2%
Status: ✅ Within Limits
See Testing Strategy for workflow testing patterns.
# Pull and run the latest image (when available)
docker pull conexus:latest
docker run -d -p 8080:8080 --name conexus conexus:latest
# Or build locally
docker build -t conexus:latest .
docker run -d -p 8080:8080 --name conexus conexus:latest
# Test the service
curl http://localhost:8080/health
Production deployment:
# Start the service
docker compose up -d
# View logs
docker compose logs -f
# Stop the service
docker compose down
# Rebuild after code changes
docker compose up -d --build
Development deployment:
# Use development configuration with debug logging
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# View debug logs
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f
Environment Variables:
# Server configuration
CONEXUS_HOST=0.0.0.0 # Server bind address
CONEXUS_PORT=8080 # Server port
# Database configuration
CONEXUS_DB_PATH=/data/conexus.db # SQLite database path
# Codebase configuration
CONEXUS_ROOT_PATH=/data/codebase # Path to codebase to index
# Logging configuration
CONEXUS_LOG_LEVEL=info # Log level (debug|info|warn|error)
CONEXUS_LOG_FORMAT=json # Log format (json|text)
# Embedding configuration (optional)
CONEXUS_EMBEDDING_PROVIDER=openai # Embedding provider (mock|openai)
CONEXUS_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-... # OpenAI API key
Volume Mounts:
volumes:
# Persistent database storage
- ./data:/data
# Optional: Mount your codebase for indexing
- /path/to/your/code:/data/codebase:ro
# Optional: Mount config file
- ./config.yml:/app/config.yml:ro
Multi-stage build:
golang:1.24-alpine (CGO enabled for SQLite)alpine:3.19 (minimal base, ca-certificates + sqlite-libs)Image specifications:
conexus:1000GET /health every 30sSecurity features:
Once running, the service exposes:
HTTP Endpoints:
# Health check
curl http://localhost:8080/health
# Response: {"status":"healthy","version":"0.1.0-alpha"}
# Service info
curl http://localhost:8080/
# Response: Service info with MCP endpoint
# MCP JSON-RPC endpoint
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
MCP Tools:
context.search - Comprehensive search with filterscontext.get_related_info - File/ticket context retrievalcontext.index_control - Indexing operationscontext.connector_management - Data source managementWith Docker Compose:
# docker-compose.prod.yml
services:
conexus:
image: conexus:latest
restart: always
environment:
- CONEXUS_LOG_LEVEL=info
- CONEXUS_LOG_FORMAT=json
volumes:
- conexus-data:/data
- /mnt/codebase:/data/codebase:ro
ports:
- "8080:8080"
healthcheck:
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
volumes:
conexus-data:
driver: local
Deploy:
docker compose -f docker-compose.prod.yml up -d
Check health:
# Container status
docker compose ps
# Health check status
docker inspect conexus | jq '.[0].State.Health'
# View logs
docker compose logs -f
# Check metrics
curl http://localhost:8080/health
Troubleshooting:
# View container logs
docker compose logs --tail=100
# Execute commands in container
docker compose exec conexus sh
# Check database
docker compose exec conexus ls -la /data/
# Restart service
docker compose restart
# Build Docker image
docker build -t conexus:custom .
# Build with specific Go version
docker build --build-arg GO_VERSION=1.24 -t conexus:custom .
# Build and tag
docker build -t conexus:v0.1.0 -t conexus:latest .
# Push to registry (configure your registry)
docker tag conexus:latest registry.example.com/conexus:latest
docker push registry.example.com/conexus:latest
docker compose logs/data directory regularlyconexus/
├── cmd/conexus/ # Main entry point
├── internal/
│ ├── agent/ # Agent implementations
│ │ ├── locator/ # File/function locator
│ │ └── analyzer/ # Code analyzer
│ ├── orchestrator/ # Workflow orchestration
│ │ ├── intent/ # Intent parsing
│ │ ├── workflow/ # Workflow engine
│ │ ├── state/ # State management
│ │ └── escalation/ # Error handling
│ ├── validation/ # Validation systems
│ │ ├── evidence/ # Evidence validation
│ │ └── schema/ # Schema validation
│ ├── profiling/ # Performance profiling
│ ├── protocol/ # JSON-RPC protocol
│ └── testing/ # Integration testing
├── pkg/schema/ # Public schemas
├── tests/fixtures/ # Test fixtures
└── docs/ # Documentation
internal/agent/myagent/type Agent interface {
Execute(ctx context.Context, req Request) (*schema.AgentOutput, error)
}
myagent_test.goSee Contributing Guide for details.
✅ All 53 integration tests passing
✅ Execution time: <1 second
✅ Evidence validation: 100%
✅ Schema compliance: 100%
✅ Real-world analysis: 5 scenarios validated
See PHASE5-STATUS.md for detailed status.
We welcome contributions! Please see:
go test ./...)This project is licensed under the MIT License - see LICENSE for details.
Built with ❤️ by the Conexus team
FAQs
Context-aware semantic search MCP server for OpenCode and other MCP clients
We found that @agentic-conexus/mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.