NEXS MCP Server

A production-ready Model Context Protocol (MCP) server built in Go

Manage AI elements (Personas, Skills, Templates, Agents, Memories, and Ensembles) with enterprise-grade architecture, high performance, comprehensive tooling, and intelligent token optimization that reduces AI context usage by 81-95% through 8 advanced optimization services including compression, streaming, deduplication, summarization, and adaptive caching.

📚 Documentation • 🚀 Quick Start • 🔧 Tools • 📦 Element Types • 💡 Examples • ⚡ Token Optimization

🎯 What is NEXS MCP?

NEXS MCP Server is a high-performance implementation of the Model Context Protocol, designed to manage AI elements with enterprise-grade architecture. Built with the official MCP Go SDK v1.1.0, it provides a robust foundation for AI system management.

Why NEXS MCP?

� Token Economy - Reduces AI context usage by 70-85% through intelligent conversation memory and keyword extraction
🌍 Multilingual Support - 11 languages supported (EN, PT, ES, FR, DE, IT, RU, JA, ZH, AR, HI) with automatic detection
�🚀 High Performance - Built in Go for speed and efficiency
🏗️ Clean Architecture - Domain-driven design with clear separation of concerns
✅ Production Ready - 70% test coverage with 500+ tests, zero race conditions, zero linter issues
🔧 96 MCP Tools - Complete portfolio (74 base + 8 optimization + 15 working memory + 3 quality scoring + others)
📦 6 Element Types - Personas, Skills, Templates, Agents, Memories, Ensembles
🔄 Dual Storage - File-based (YAML) or in-memory storage modes
🌐 Cross-Platform - Binaries for Linux, macOS, Windows (amd64/arm64)
🐳 Docker Ready - Multi-arch Docker images with security hardening
📊 Analytics - Built-in performance monitoring and usage statistics

Use Cases

Token Optimization - Reduce AI API costs by 81-95% with 8 intelligent optimization services: response compression (gzip/zlib), streaming responses, semantic deduplication, TF-IDF summarization, context window management, adaptive caching, batch processing, and prompt compression
Memory Consolidation - HNSW-based duplicate detection, DBSCAN/K-means clustering, knowledge graph extraction with NLP entities & relationships (Sprint 14)
Quality Scoring - Built-in ONNX models for content quality assessment (MS MARCO for speed, Paraphrase-Multilingual for quality)
AI System Management - Centralized management of AI personas, skills, and workflows
Portfolio Organization - Organize and version control AI elements with GitHub integration
Team Collaboration - Share collections of elements across teams via GitHub
Development Workflows - Automate AI element creation and deployment
Context Management - Store and retrieve conversation memories with deduplication and automatic language detection
Multi-Agent Systems - Orchestrate ensembles of agents with sophisticated execution strategies
Multilingual Applications - Support conversations in 11 languages with automatic detection and optimized stop word filtering

✨ Key Features

Core Infrastructure

✅ Official MCP SDK - Built on github.com/modelcontextprotocol/go-sdk v1.2.0
✅ Clean Architecture - Domain-driven design with clear separation of concerns
✅ High Test Coverage - 76.4% application, 91.7% HNSW, 96.7% TF-IDF with 295 tests, zero race conditions, zero linter issues
✅ Dual Storage Modes - File-based YAML or in-memory
✅ 104 MCP Tools - Complete portfolio with consolidation, optimization, temporal features, and task scheduling
✅ 8 Token Optimization Services - Compression, streaming, deduplication, summarization, context management, adaptive caching, batch processing, prompt compression
✅ 6 Element Types - Persona, Skill, Template, Agent, Memory, Ensemble
✅ 21 Application Services - Including 4 new consolidation services (Sprint 14)
✅ Stdio Transport - Standard MCP communication over stdin/stdout
✅ Thread-Safe - Concurrent operations with proper synchronization
✅ Cross-Platform - Binaries for Linux, macOS, Windows (amd64/arm64)

GitHub Integration

✅ OAuth Authentication - Secure device flow authentication
✅ Portfolio Sync - Push/pull elements to/from GitHub repositories
✅ Collection System - Install, manage, and publish element collections
✅ PR Submission - Submit elements to collections via automated PRs
✅ Conflict Detection - Smart conflict resolution with multiple strategies
✅ Incremental Sync - Efficient delta-based synchronization

Production Features

✅ Auto-Save - Automatic conversation context preservation with multilingual keyword extraction (11 languages)
✅ Token Optimization - 81-95% reduction in AI context usage through 8 optimization services: compression (gzip/zlib 70-75%), streaming (prevent overflow), semantic deduplication (92%+ similarity), TF-IDF summarization (70% reduction), context window management (smart truncation), adaptive cache (dynamic TTL 1h-7d), batch processing (10x faster), and prompt compression (35% reduction)
✅ ONNX Quality Scoring - Built-in models for content quality assessment
- MS MARCO MiniLM-L-6-v2 (default): 61.64ms latency, 9 languages (non-CJK), ~16 inf/s throughput
- Paraphrase-Multilingual-MiniLM-L12-v2 (configurable): 109.41ms latency, 11 languages including CJK, 71% more effective
- Multi-tier fallback: ONNX → Groq API → Gemini API → Implicit Signals
- Quality-based retention policies (High: 365d, Medium: 180d, Low: 90d)
- Configuration Guide | Benchmarks
✅ Working Memory System - Session-scoped memory with priority-based TTL (15 tools)
- Priority levels: Low (1h), Medium (4h), High (12h), Critical (24h)
- Auto-promotion to long-term storage based on access patterns
- Background cleanup every 5 minutes
- API Documentation
✅ Background Task Scheduler - Robust scheduling system (Sprint 11)
- Cron-like expressions: wildcards, ranges, steps, lists
- Priority-based execution: Low/Medium/High
- Task dependencies with validation
- Persistent storage with JSON and atomic writes
- Auto-retry with configurable delays
- API Documentation
✅ Temporal Features - Time travel and version history (Sprint 11 - 4 tools)
- Version history with snapshot/diff compression
- Confidence decay: exponential, linear, logarithmic, step
- Time travel queries: reconstruct graph at any point in time
- Critical relationship preservation
- API Documentation | User Guide
✅ Multilingual Memory - Automatic language detection (EN, PT, ES, FR, DE, IT, RU, JA, ZH, AR, HI) with language-specific stop word filtering
✅ Quick Create Tools - Simplified element creation with template defaults
✅ Backup & Restore - Portfolio backup with tar.gz compression and SHA-256 checksums
✅ Memory Management - Search, summarize, update memories with relevance scoring
✅ Structured Logging - slog-based JSON/text logs with context extraction
✅ Log Query Tools - Filter and search logs by level, user, operation, tool
✅ User Identity - Session management with metadata support
✅ Analytics Dashboard - Usage statistics and performance metrics (p50/p95/p99)

Ensemble Capabilities

✅ Sequential Execution - Run agents in order with context sharing
✅ Parallel Execution - Run agents concurrently for speed
✅ Hybrid Execution - Mix sequential and parallel strategies
✅ Aggregation Strategies - First, last, consensus, voting, all, merge
✅ Monitoring - Real-time progress tracking and callbacks
✅ Fallback Chains - Automatic failover to backup agents

📊 Project Status

Version:               v1.3.0 (Sprint 14 Complete)
Application Coverage:   76.4% ✓ (+13.2%)
HNSW Index:            91.7% ✓
TF-IDF Index:          96.7% ✓
Template Layer:        87.0% ✓
Portfolio Layer:       75.6% ✓
Lines of Code:         ~82,075 (40,240 production + 41,835 tests)
Test Cases:            295 tests (100% passing, 0 race conditions)
MCP Tools:             104 (26 element + 9 memory + 15 working + 10 consolidation + others)
Application Services:  21 (4 new consolidation services)
Element Types:         6 (Persona, Skill, Template, Agent, Memory, Ensemble)
ONNX Models:           2 (MS MARCO default, Paraphrase-Multilingual configurable)
Quality:               Zero race conditions, Zero linter issues
Token Optimization:    81-95% economy (8 services integrated)

Recent Milestones:

✅ Sprint 14 Complete (26/12/2025) - Advanced Application Services Test Coverage (295 tests, 76.4% coverage, 10 consolidation tools)
✅ v1.3.0 Release (24/12/2025) - Token Optimization (8 services: compression, streaming, deduplication, summarization, context, cache, batch, prompt compression)
✅ v1.2.0 Release (24/12/2025) - Task Scheduler + Temporal Features (Sprint 11 complete)
✅ v1.1.0 Release (23/12/2025) - ONNX Quality Scoring + Working Memory System + 91 MCP Tools
✅ v1.0.1 Release (20/12/2025) - Community infrastructure, benchmarks, template validator enhancements
✅ v1.0.0 Release (19/12/2025) - Production release with 66 MCP tools, GitHub integration, NPM distribution

🚀 Quick Start

Installation

Choose your preferred installation method:

Option 1: NPM (Recommended - Cross-platform)

# Install globally
npm install -g @fsvxavier/nexs-mcp-server

# Verify installation
nexs-mcp --version

📦 NPM Package: https://www.npmjs.com/package/@fsvxavier/nexs-mcp-server

Option 2: Go Install (For Go developers)

go install github.com/fsvxavier/nexs-mcp/cmd/nexs-mcp@v1.3.0

Option 3: Homebrew (macOS/Linux)

# Add tap
brew tap fsvxavier/nexs-mcp

# Install
brew install nexs-mcp

# Verify installation
nexs-mcp --version

Option 4: Docker (Containerized)

# Pull image from Docker Hub
docker pull fsvxavier/nexs-mcp:latest

# Or pull specific version
docker pull fsvxavier/nexs-mcp:v1.3.0

# Run with volume mount
docker run -v $(pwd)/data:/app/data fsvxavier/nexs-mcp:latest

# Or use Docker Compose
docker-compose up -d

🐳 Docker Hub: https://hub.docker.com/r/fsvxavier/nexs-mcp
📦 Image Size: 14.5 MB (compressed), 53.7 MB (uncompressed)

Option 5: Build from Source

# Clone repository
git clone https://github.com/fsvxavier/nexs-mcp.git
cd nexs-mcp

# Install dependencies
go mod download

# Build
make build

# Run tests
make test-coverage

# Run server
./bin/nexs-mcp

First Run

File Storage (default):

# Default configuration (file storage in data/elements)
nexs-mcp

# Custom data directory
nexs-mcp -data-dir /path/to/data

# Or via environment variable
NEXS_DATA_DIR=/path/to/data nexs-mcp

In-Memory Storage:

# Memory-only storage (data lost on restart)
nexs-mcp -storage memory

# Or via environment variable
NEXS_STORAGE_TYPE=memory nexs-mcp

Output:

NEXS MCP Server v1.0.0
Initializing Model Context Protocol server...
Storage type: file
Data directory: data/elements
Registered 66 tools
Server ready. Listening on stdio...

Integration with Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexs-mcp": {
      "command": "nexs-mcp",
      "args": [],
      "env": {
        "NEXS_DATA_DIR": "/path/to/your/elements",
        "NEXS_STORAGE_TYPE": "file"
      }
    }
  }
}

Restart Claude Desktop and you'll see NEXS MCP tools available!

For detailed setup instructions, see docs/user-guide/GETTING_STARTED.md

🔧 Available Tools

NEXS MCP provides 96 MCP tools organized into categories:

🗂️ Element Management (11 tools)

Generic CRUD Operations:

list_elements - List all elements with advanced filtering (type, active_only, tags)
get_element - Get element details by ID
create_element - Create generic element
update_element - Update existing element
delete_element - Delete element by ID

Type-Specific Creation: 6. create_persona - Create Persona with behavioral traits 7. create_skill - Create Skill with triggers and procedures 8. create_template - Create Template with variable substitution 9. create_agent - Create Agent with goals and workflows 10. create_memory - Create Memory with content hashing 11. create_ensemble - Create Ensemble for multi-agent orchestration

⚡ Quick Create Tools (6 tools)

quick_create_persona - Simplified persona creation with minimal prompts
quick_create_skill - Simplified skill creation
quick_create_template - Simplified template creation
quick_create_agent - Simplified agent creation
quick_create_memory - Simplified memory creation
quick_create_ensemble - Simplified ensemble creation

📚 Collection System (10 tools)

browse_collections - Discover available collections (GitHub, local, HTTP)
install_collection - Install collection from URI (github://, file://, https://)
uninstall_collection - Remove installed collection
list_installed_collections - List all installed collections
get_collection_info - Get detailed collection information
export_collection - Export collection to tar.gz archive
update_collection - Update specific collection
update_all_collections - Update all installed collections
check_collection_updates - Check for available updates
publish_collection - Publish collection to GitHub

🐙 GitHub Integration (8 tools)

github_auth_start - Initiate OAuth2 device flow authentication
github_auth_status - Check GitHub authentication status
github_list_repos - List user's GitHub repositories
github_sync_push - Push local elements to GitHub repository
github_sync_pull - Pull elements from GitHub repository
github_sync_bidirectional - Two-way sync with conflict resolution
submit_element_to_collection - Submit element via automated PR
track_pr_status - Track PR submission status

💾 Backup & Restore (4 tools)

backup_portfolio - Create compressed backup with checksums
restore_portfolio - Restore from backup with validation
activate_element - Activate element (shortcut for update)
deactivate_element - Deactivate element (shortcut for update)

🧠 Memory Management (5 tools)

search_memory - Search memories with relevance scoring
summarize_memories - Get memory statistics and summaries
update_memory - Partial update of memory content
delete_memory - Delete specific memory
clear_memories - Bulk delete memories with filters

🎯 Memory Quality System (3 tools)

score_memory_quality - ONNX-based quality scoring with multi-tier fallback
get_retention_policy - Get retention policy for quality score
get_retention_stats - Memory retention statistics and quality distribution

📊 Analytics & Monitoring (11 tools)

duplicate_element - Duplicate element with new ID and optional name
get_usage_stats - Analytics with period filtering and top-10 rankings
get_performance_dashboard - Performance metrics with p50/p95/p99 latencies
list_logs - Query logs with filters (level, date, user, operation, tool)
get_current_user - Get current user session information
set_user_context - Set user identity with metadata
clear_user_context - Clear current user session
get_context - Get MCP server context information
search_elements - Advanced element search with filters
execute_ensemble - Execute ensemble with monitoring
get_ensemble_status - Get ensemble execution status

🔍 Context Enrichment System (3 tools)

expand_memory_context - Expand memory context by fetching related elements
find_related_memories - Find memories that reference a specific element (reverse search)
suggest_related_elements - Get intelligent recommendations based on relationships and patterns

🔗 Relationship System (5 tools)

get_related_elements - Bidirectional search with O(1) lookups (forward/reverse/both)
expand_relationships - Recursive expansion up to 5 levels with depth control
infer_relationships - Automatic inference (mention, keyword, semantic, pattern)
get_recommendations - Intelligent recommendations with 4 scoring strategies
get_relationship_stats - Index statistics (entries, cache hit rate)

🎨 Template System (4 tools)

list_templates - List available templates with filtering
get_template - Retrieve complete template details
instantiate_template - Instantiate template with variables (Handlebars)
validate_template - Validate template syntax and variables

✅ Validation & Rendering (2 tools)

validate_element - Type-specific validation (basic/comprehensive/strict)
render_template - Render template directly without creating element

🔄 Operations (2 tools)

reload_elements - Hot reload elements without server restart
search_portfolio_github - Search GitHub repositories for NEXS portfolios

🧠 Working Memory System (15 tools)

working_memory_add - Add entry to working memory with session scoping
working_memory_get - Retrieve working memory and record access
working_memory_list - List all memories in session with filters
working_memory_promote - Manually promote to long-term storage
working_memory_clear_session - Clear all memories in session
working_memory_update - Update existing working memory
working_memory_delete - Delete specific working memory
working_memory_search - Search within session memories
working_memory_stats - Get session statistics
working_memory_extend_ttl - Extend TTL of specific memory
working_memory_set_priority - Change memory priority
working_memory_add_tags - Add tags to existing memory
working_memory_remove_tags - Remove tags from memory
working_memory_get_promoted - List promoted memories
working_memory_cleanup - Manual cleanup trigger

Features:

Session-scoped isolation
Priority-based TTL (Low: 1h, Medium: 4h, High: 12h, Critical: 24h)
Auto-promotion based on access patterns
Background cleanup every 5 minutes
Full metadata and tag support

Documentation: Working Memory Tools API

⚡ Token Optimization System (8 tools) NEW in v1.3.0

deduplicate_memories - Find and merge semantically similar memories (92%+ similarity threshold)
optimize_context - Optimize conversation context for token efficiency using all optimization services
get_optimization_stats - Comprehensive statistics for all 8 optimization services
summarize_memory - Summarize specific memory using TF-IDF extractive summarization
compress_response - Manually compress response using gzip/zlib (70-75% reduction)
stream_large_list - Stream large element lists in chunks (prevent memory overflow)
batch_create_elements - Create multiple elements in parallel (10x faster)
get_cache_stats - Adaptive cache statistics (access patterns, TTL distribution)

8 Optimization Services:

Response Compression - Gzip/zlib compression (70-75% size reduction)
Streaming Handler - Chunked streaming (prevent memory overflow)
Semantic Deduplication - Similarity-based duplicate detection (92%+ threshold)
Auto-Summarization - TF-IDF extractive summarization (70% compression)
Context Window Manager - Smart truncation strategies (preserve recent + relevant)
Adaptive Cache - Dynamic TTL based on access patterns (1h-7d)
Batch Processing - Parallel execution for bulk operations (10x faster)
Prompt Compression - Remove redundancies and fillers (35% reduction)

Performance:

Overall token reduction: 81-95% in production workloads (target: 90-95%)
Zero additional latency overhead
Configurable per-service via environment variables
Comprehensive metrics and monitoring

Documentation: Token Optimization System

🎯 Memory Quality System (3 tools)

score_memory_quality - ONNX-based quality scoring with multi-tier fallback (ONNX → Groq → Gemini → Implicit)
get_retention_policy - Get retention policy for quality score (High: 365d, Medium: 180d, Low: 90d)
get_retention_stats - Memory retention statistics and quality distribution

Features:

2 ONNX models: MS MARCO (default, 61.64ms) and Paraphrase-Multilingual (configurable, 109.41ms)
Multi-tier fallback system for reliability
Automatic quality-based retention policies
Zero cost, full privacy, offline-capable

Documentation: ONNX Model Configuration | Benchmarks

For semantic search tools (73-74), see relationship system above.

For detailed tool documentation, see docs/user-guide/QUICK_START.md

📦 Element Types

NEXS MCP supports 6 element types for comprehensive AI system management:

Element	Purpose	Key Features	Documentation
Persona	AI behavior and personality	Behavioral traits, expertise areas, communication style	PERSONA.md
Skill	Reusable capabilities	Triggers, procedures, execution strategies	SKILL.md
Template	Content generation	Variable substitution, dynamic rendering	TEMPLATE.md
Agent	Autonomous workflows	Goals, planning, execution	AGENT.md
Memory	Context persistence	Content storage, deduplication, search	MEMORY.md
Ensemble	Multi-agent orchestration	Sequential/parallel execution, voting, consensus	ENSEMBLE.md

Quick Element Creation Examples

Create a Persona:

{
  "tool": "quick_create_persona",
  "arguments": {
    "name": "Technical Writer",
    "description": "Expert in writing clear technical documentation",
    "expertise": ["documentation", "technical writing", "API design"],
    "traits": ["clear", "concise", "thorough"]
  }
}

Create a Skill:

{
  "tool": "quick_create_skill",
  "arguments": {
    "name": "Code Review",
    "description": "Review code for best practices and bugs",
    "triggers": ["code review", "pr review"],
    "procedure": "1. Check code style\n2. Verify logic\n3. Suggest improvements"
  }
}

Create an Ensemble:

{
  "tool": "quick_create_ensemble",
  "arguments": {
    "name": "Documentation Team",
    "description": "Multi-agent documentation generation",
    "members": ["persona:technical-writer", "agent:proofreader"],
    "execution_mode": "sequential",
    "aggregation_strategy": "merge"
  }
}

For complete element documentation, see docs/elements/README.md

💡 Usage Examples

Basic Element Operations

List all elements:

{
  "tool": "list_elements",
  "arguments": {
    "type": "persona",
    "active_only": true
  }
}

Get element details:

{
  "tool": "get_element",
  "arguments": {
    "id": "persona-technical-writer"
  }
}

Update element:

{
  "tool": "update_element",
  "arguments": {
    "id": "persona-technical-writer",
    "updates": {
      "expertise": ["documentation", "technical writing", "API design", "Markdown"]
    }
  }
}

GitHub Integration

Authenticate with GitHub:

{
  "tool": "github_auth_start",
  "arguments": {}
}
// Returns: user_code, verification_uri, expires_in
// Visit https://github.com/login/device and enter the code

Sync portfolio to GitHub:

{
  "tool": "github_sync_push",
  "arguments": {
    "repo_owner": "yourusername",
    "repo_name": "my-ai-portfolio",
    "branch": "main",
    "commit_message": "Update personas and skills"
  }
}

Pull elements from GitHub:

{
  "tool": "github_sync_pull",
  "arguments": {
    "repo_owner": "yourusername",
    "repo_name": "my-ai-portfolio",
    "branch": "main",
    "strategy": "newest-wins"
  }
}

Collection Management

Browse available collections:

{
  "tool": "browse_collections",
  "arguments": {
    "source": "github",
    "query": "technical writing"
  }
}

Install a collection:

{
  "tool": "install_collection",
  "arguments": {
    "uri": "github://fsvxavier/nexs-collections/technical-writing",
    "force": false
  }
}

Submit element to collection:

{
  "tool": "submit_element_to_collection",
  "arguments": {
    "element_id": "persona-technical-writer",
    "collection_repo": "fsvxavier/nexs-collections",
    "category": "personas"
  }
}

Backup & Restore

Create backup:

{
  "tool": "backup_portfolio",
  "arguments": {
    "output_path": "/backups/portfolio-2025-12-20.tar.gz",
    "compression": "best",
    "include_inactive": false
  }
}

Restore from backup:

{
  "tool": "restore_portfolio",
  "arguments": {
    "backup_path": "/backups/portfolio-2025-12-20.tar.gz",
    "strategy": "merge",
    "dry_run": false
  }
}

Memory Management

Search memories:

{
  "tool": "search_memory",
  "arguments": {
    "query": "machine learning optimization techniques",
    "limit": 10,
    "min_relevance": 5
  }
}

Summarize memories:

{
  "tool": "summarize_memories",
  "arguments": {
    "author_filter": "alice",
    "type_filter": "semantic"
  }
}

Add to working memory:

{
  "tool": "working_memory_add",
  "arguments": {
    "session_id": "user-session-123",
    "content": "Meeting notes from today's standup",
    "priority": "high",
    "tags": ["meeting", "standup"]
  }
}

Promote to long-term:

{
  "tool": "working_memory_promote",
  "arguments": {
    "session_id": "user-session-123",
    "memory_id": "working_memory_..."
  }
}

Score memory quality:

{
  "tool": "score_memory_quality",
  "arguments": {
    "memory_id": "memory-xyz",
    "context": "technical documentation"
  }
}

Analytics

Get usage statistics:

{
  "tool": "get_usage_stats",
  "arguments": {
    "period": "30d",
    "include_top_n": 10
  }
}

Performance dashboard:

{
  "tool": "get_performance_dashboard",
  "arguments": {
    "period": "7d"
  }
}
// Returns p50/p95/p99 latencies, slow operations, error rates

Ensemble Execution

Execute ensemble:

{
  "tool": "execute_ensemble",
  "arguments": {
    "ensemble_id": "documentation-team",
    "input": "Write API documentation for the /users endpoint",
    "context": {
      "api_version": "v2.0",
      "format": "OpenAPI"
    }
  }
}

For more examples, see:

Quick Start Guide - 10 hands-on tutorials
Examples Directory - Complete workflows and integration examples

📁 Project Structure

nexs-mcp/
├── cmd/nexs-mcp/          # Application entrypoint
├── internal/
│   ├── domain/            # Business logic (79.2% coverage)
│   │   ├── element.go            # Base element interface
│   │   ├── persona.go            # Persona domain model
│   │   ├── skill.go              # Skill domain model
│   │   ├── template.go           # Template domain model
│   │   ├── agent.go              # Agent domain model
│   │   ├── memory.go             # Memory domain model
│   │   └── ensemble.go           # Ensemble domain model
│   ├── application/       # Use cases and services
│   │   ├── ensemble_executor.go  # Ensemble execution engine
│   │   ├── ensemble_monitor.go   # Real-time monitoring
│   │   ├── ensemble_aggregation.go # Voting & consensus
│   │   └── statistics.go         # Analytics service
│   ├── infrastructure/    # External adapters (68.1% coverage)
│   │   ├── repository.go          # In-memory repository
│   │   ├── file_repository.go     # File-based YAML repository
│   │   ├── github_client.go       # GitHub API client
│   │   ├── github_oauth.go        # OAuth2 device flow
│   │   ├── sync_conflict_detector.go  # Conflict resolution
│   │   ├── sync_metadata.go       # Sync state tracking
│   │   ├── sync_incremental.go    # Incremental sync
│   │   └── pr_tracker.go          # PR submission tracking
│   ├── mcp/              # MCP protocol layer (66.8% coverage)
│   │   ├── server.go             # MCP server (66 tools)
│   │   ├── tools.go              # Element CRUD tools
│   │   ├── quick_create_tools.go # Quick create tools
│   │   ├── collection_tools.go   # Collection management
│   │   ├── github_tools.go       # GitHub integration
│   │   ├── github_portfolio_tools.go # Portfolio sync
│   │   ├── backup_tools.go       # Backup & restore
│   │   ├── memory_tools.go       # Memory management
│   │   ├── log_tools.go          # Log querying
│   │   ├── user_tools.go         # User identity
│   │   ├── analytics_tools.go    # Usage & performance stats
│   │   └── ensemble_execution_tools.go # Ensemble execution
│   ├── backup/           # Backup & restore services (56.3% coverage)
│   ├── logger/           # Structured logging (92.1% coverage)
│   ├── config/           # Configuration (100% coverage)
│   ├── collection/       # Collection system (58.6% coverage)
│   ├── validation/       # Validation logic
│   └── portfolio/        # Portfolio management (75.6% coverage)
├── data/                 # File storage (gitignored)
│   └── elements/         # YAML element storage
├── docs/                 # Complete documentation
│   ├── user-guide/       # User documentation
│   │   ├── GETTING_STARTED.md   # Onboarding guide
│   │   ├── QUICK_START.md       # 10 tutorials
│   │   └── TROUBLESHOOTING.md   # Common issues
│   ├── elements/         # Element type documentation
│   ├── deployment/       # Deployment guides
│   ├── adr/             # Architecture Decision Records
│   └── README.md        # Documentation index
├── examples/            # Usage examples
│   ├── basic/           # Basic examples
│   ├── integration/     # Integration examples
│   └── workflows/       # Complete workflows
├── homebrew/            # Homebrew formula
├── .github/workflows/   # CI/CD pipelines
├── CHANGELOG.md         # Version history
├── COVERAGE_REPORT.md   # Test coverage analysis
├── NEXT_STEPS.md        # Development roadmap
├── docker-compose.yml   # Docker Compose config
├── Dockerfile           # Multi-stage Docker build
├── Makefile            # Build targets
└── go.mod              # Go module definition

🛠️ Development

Prerequisites

Go 1.25+
Make (optional, for convenience targets)
Docker (optional, for containerized deployment)

Building

# Clone repository
git clone https://github.com/fsvxavier/nexs-mcp.git
cd nexs-mcp

# Install dependencies
go mod download

# Build binary
make build
# or
go build -o bin/nexs-mcp ./cmd/nexs-mcp

# Run tests
make test-coverage
# or
go test -coverprofile=coverage.out ./...

# View coverage report
go tool cover -html=coverage.out

Make Targets

make build             # Build binary
make test              # Run tests
make test-coverage     # Run tests with coverage report
make lint              # Run linters (golangci-lint)
make verify            # Run all verification steps
make ci                # Run full CI pipeline
make clean             # Clean build artifacts

Running Locally

# Run with default settings (file storage)
./bin/nexs-mcp

# Run with custom data directory
./bin/nexs-mcp -data-dir ./my-elements

# Run in memory mode
./bin/nexs-mcp -storage memory

# Enable debug logging
./bin/nexs-mcp -log-level debug

# Run with environment variables
NEXS_DATA_DIR=./my-elements \
NEXS_STORAGE_TYPE=file \
NEXS_LOG_LEVEL=debug \
./bin/nexs-mcp

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./internal/domain/...

# Run specific test
go test -run TestPersonaValidation ./internal/domain/

# Run with verbose output
go test -v ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

📚 Documentation

User Documentation

Getting Started Guide - Installation, first run, Claude Desktop integration
Quick Start Tutorial - 10 hands-on tutorials (2-5 min each)
ONNX Model Configuration - Quality scoring models (MS MARCO vs Paraphrase-Multilingual)
Troubleshooting Guide - Common issues, FAQ, error codes
Documentation Index - Complete documentation navigation

Element Types

Elements Overview - Quick reference and relationships
Persona Documentation - Behavioral traits and expertise
Skill Documentation - Triggers and procedures
Template Documentation - Variable substitution
Agent Documentation - Goal-oriented workflows
Memory Documentation - Content deduplication
Ensemble Documentation - Multi-agent orchestration

Deployment

Docker Deployment - Complete Docker guide (600+ lines)
NPM Installation - NPM package usage
Homebrew Installation - Homebrew tap setup

Architecture & Development

ADR-001: Hybrid Collection Architecture
ADR-007: MCP Resources Implementation
ADR-008: Collection Registry Production
ADR-009: Element Template System
ADR-010: Missing Element Tools
Test Coverage Report - Coverage analysis and gaps

Benchmarks & Quality

ONNX Benchmark Results - Performance comparison of MS MARCO vs Paraphrase-Multilingual models
ONNX Quality Audit - Technical audit of quality system (80% conforme)
Quality Usage Analysis - Internal usage analysis (100% conforme)

Project Planning

Roadmap - Future milestones
Next Steps - Current development status
Changelog - Version history and release notes

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make test-coverage)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

Follow Clean Architecture principles
Maintain test coverage (aim for 80%+)
Use meaningful commit messages
Document public APIs with godoc comments
Run make verify before submitting PRs

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with the official MCP Go SDK
Inspired by the Model Context Protocol specification
Thanks to all contributors

📧 Support

Documentation: docs/README.md
Issues: GitHub Issues
Discussions: GitHub Discussions

⬆ Back to Top

Made with ❤️ by the NEXS MCP team

Nexs MCP

NEXS MCP Server

🎯 What is NEXS MCP?

Why NEXS MCP?

Use Cases

✨ Key Features

Core Infrastructure

GitHub Integration

Production Features

Ensemble Capabilities

📊 Project Status

🚀 Quick Start

Installation

Option 1: NPM (Recommended - Cross-platform)

Option 2: Go Install (For Go developers)

Option 3: Homebrew (macOS/Linux)

Option 4: Docker (Containerized)

Option 5: Build from Source

First Run

Integration with Claude Desktop

🔧 Available Tools

🗂️ Element Management (11 tools)

⚡ Quick Create Tools (6 tools)

📚 Collection System (10 tools)

🐙 GitHub Integration (8 tools)

💾 Backup & Restore (4 tools)

🧠 Memory Management (5 tools)

🎯 Memory Quality System (3 tools)

📊 Analytics & Monitoring (11 tools)

🔍 Context Enrichment System (3 tools)

🔗 Relationship System (5 tools)

🎨 Template System (4 tools)

✅ Validation & Rendering (2 tools)

🔄 Operations (2 tools)

🧠 Working Memory System (15 tools)

⚡ Token Optimization System (8 tools) NEW in v1.3.0

🎯 Memory Quality System (3 tools)

📦 Element Types

Quick Element Creation Examples

💡 Usage Examples

Basic Element Operations

GitHub Integration

Collection Management

Backup & Restore

Memory Management

Analytics

Ensemble Execution

📁 Project Structure

🛠️ Development

Prerequisites

Building

Make Targets

Running Locally

Running Tests

📚 Documentation

User Documentation

Element Types

Deployment

Architecture & Development

Benchmarks & Quality

Project Planning

🤝 Contributing

Development Workflow

Code Standards

📝 License

🙏 Acknowledgments

📧 Support

Related Servers

TickTick

Zapier

MoLing MCP Server

Yandex Browser Tabs

Hilanet MCP

PDF Reader

Feishu MCP Server

Adobe Express

Redmine MCP

Notion MCP Server