@fsvxavier/nexs-mcp-server

v1.4.0

Published

4 months ago

NEXS MCP Server - Model Context Protocol server for portfolio management with NPM distribution

Downloads

0High
0Medium
0Low

fsvxavier

mcp model-context-protocol ai portfolio claude anthropic nexs

NEXS MCP Server - NPM Package

A production-ready Model Context Protocol (MCP) server for managing AI elements (Personas, Skills, Templates, Agents, Memories, and Ensembles). Features intelligent token optimization that reduces AI context usage by 81-95% through 8 optimization services: response compression (gzip/zlib), streaming, semantic deduplication, TF-IDF summarization, context window management, adaptive caching, batch processing, and prompt compression. Also includes multilingual support (11 languages), ONNX-based quality scoring, session-scoped working memory with priority-based TTL, background task scheduler with cron support, temporal features with time travel queries, and advanced memory consolidation with duplicate detection, clustering, and knowledge graphs (Sprint 14).

Stats: 295 tests (100% passing), 76.4% coverage, 104 MCP tools, 21 application services, 0 race conditions, 0 lint issues.

🚀 Quick Start

Installation

Install globally via NPM:

npm install -g @fsvxavier/nexs-mcp-server

Or use with npx without installation:

npx @fsvxavier/nexs-mcp-server

Verify Installation

nexs-mcp --version
# Output: NEXS MCP Server v1.4.0

First Run

# Run with default configuration (file storage in data/elements)
nexs-mcp

# Run with custom data directory
nexs-mcp -data-dir /path/to/data

# Run in memory mode
nexs-mcp -storage memory

Output:

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

📦 What's Included

This NPM package includes:

Cross-platform binaries for:
- macOS (Intel and Apple Silicon)
- Linux (amd64 and arm64)
- Windows (amd64)
Automatic platform detection and binary selection
96 MCP tools for comprehensive AI element management:
- 74 base tools (CRUD, collections, GitHub, backup, analytics)
- 8 token optimization tools (compression, streaming, deduplication, summarization, context, cache, batch, prompt compression)
- 15 working memory tools (session-scoped with priority-based TTL)
- 4 template tools (list, get, preview, render)
- 3 quality scoring tools (ONNX-based with multi-tier fallback)
- 4 temporal tools (version history, confidence decay, time travel)
6 element types: Persona, Skill, Template, Agent, Memory, Ensemble
Dual storage modes: File-based (YAML) or in-memory
💰 Token optimization: 81-95% reduction in AI context usage through 8 optimization services
🌍 Multilingual support: 11 languages (EN, PT, ES, FR, DE, IT, RU, JA, ZH, AR, HI) with automatic detection
🎯 ONNX Quality Scoring: 2 models with benchmarks (MS MARCO 61.64ms, Paraphrase-Multilingual 109.41ms)
🧠 Working Memory: Session-scoped with auto-promotion and priority-based TTL

🔧 Usage

Command Line

# Basic usage
nexs-mcp

# Custom data directory
nexs-mcp -data-dir ./my-elements

# Memory-only storage
nexs-mcp -storage memory

# Enable debug logging
nexs-mcp -log-level debug

# Show help
nexs-mcp --help

Environment Variables

You can also configure via environment variables:

# Set data directory
export NEXS_DATA_DIR=/path/to/data

# Set storage type
export NEXS_STORAGE_TYPE=file  # or 'memory'

# Set log level
export NEXS_LOG_LEVEL=debug  # or 'info', 'warn', 'error'

# Run
nexs-mcp

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"
      }
    }
  }
}

Or use npx if you don't want global installation:

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

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

✨ Features

Core Capabilities

💰 Token Optimization - 70-85% reduction in AI context usage through intelligent conversation memory
🌍 Multilingual Support - 11 languages (EN, PT, ES, FR, DE, IT, RU, JA, ZH, AR, HI) with automatic detection
91 MCP Tools - Complete portfolio management, GitHub integration, analytics, working memory, quality scoring
6 Element Types - Persona, Skill, Template, Agent, Memory, Ensemble
Dual Storage - File-based (YAML) or in-memory
GitHub Integration - OAuth, portfolio sync, collection management, PR submission
Production Features - Backup/restore, memory management, logging, analytics
Ensemble Execution - Sequential/parallel/hybrid with voting and consensus
🎯 ONNX Quality Scoring - MS MARCO (default, 61.64ms) and Paraphrase-Multilingual (configurable, 109.41ms)
🧠 Working Memory - Session-scoped with priority-based TTL and auto-promotion

Element Types

| Element | Purpose | Key Features | |---------|---------|--------------| | Persona | AI behavior and personality | Traits, expertise, communication style | | Skill | Reusable capabilities | Triggers, procedures, execution strategies | | Template | Content generation | Variable substitution, dynamic rendering | | Agent | Autonomous workflows | Goals, planning, execution | | Memory | Context persistence | Content storage, deduplication, search, multilingual keyword extraction, 70-85% token savings | | Ensemble | Multi-agent orchestration | Sequential/parallel execution, consensus |

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 Resolution - Smart conflict resolution with multiple strategies

📚 Documentation

User Guides

Getting Started - Installation, first run, Claude Desktop integration
Quick Start Tutorial - 10 hands-on tutorials (2-5 min each)
Troubleshooting - Common issues, FAQ, error codes

Element Documentation

Persona - Behavioral traits and expertise
Skill - Triggers and procedures
Template - Variable substitution
Agent - Goal-oriented workflows
Memory - Content deduplication
Ensemble - Multi-agent orchestration

API Reference

See Main README for complete tool reference.

See Working Memory Tools API for working memory documentation.

See ONNX Model Configuration for quality scoring configuration.

See Benchmark Results for ONNX performance comparison.

💡 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"]
  }
}

Sync with GitHub

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

Install a Collection

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

Create Backup

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

Working Memory

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

Quality Scoring

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

For more examples, see Examples Directory.

🔧 Troubleshooting

Binary Not Found

If you get "command not found" after installation:

# Check npm global bin directory
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

Platform Not Supported

If your platform is not supported, you can:

Use Docker: docker pull fsvxavier/nexs-mcp:latest
Build from source: See build instructions

Permission Denied

On Linux/macOS, if you get permission errors:

# Install without sudo (recommended)
npm install -g --unsafe-perm @fsvxavier/nexs-mcp-server

# Or use npx instead
npx @fsvxavier/nexs-mcp-server

Connection Issues with Claude Desktop

If Claude Desktop can't connect:

Verify the binary path: which nexs-mcp
Test the binary: nexs-mcp --version
Check Claude Desktop logs (see troubleshooting guide)
Ensure correct configuration in claude_desktop_config.json

For more troubleshooting, see Troubleshooting Guide.

🏗️ Project Information

About NEXS MCP

NEXS MCP Server is a high-performance Model Context Protocol implementation built in Go with Clean Architecture. It provides enterprise-grade AI element management with comprehensive tooling.

Version: v1.1.0
GitHub Repository: https://github.com/fsvxavier/nexs-mcp
NPM Package: https://www.npmjs.com/package/@fsvxavier/nexs-mcp-server
Docker Hub: https://hub.docker.com/r/fsvxavier/nexs-mcp
Documentation: https://github.com/fsvxavier/nexs-mcp/tree/main/docs

Key Features v1.1.0

91 MCP Tools (66 base + 5 relationships + 2 semantic + 15 working memory + 3 quality scoring)
ONNX Quality Scoring with 2 production models and benchmarks
Working Memory System with session-scoped TTL and auto-promotion
Token Optimization reducing AI context usage by 70-85%
Multilingual Support for 11 languages with automatic detection

Technology Stack

Language: Go 1.25
MCP SDK: github.com/modelcontextprotocol/go-sdk v1.1.0
Architecture: Clean Architecture with Domain-Driven Design
Storage: File-based (YAML) and in-memory
Test Coverage: 63.2% overall (607+ tests, 425+ new in v1.1.0)
ONNX Models: MS MARCO MiniLM-L-6-v2 (default), Paraphrase-Multilingual-MiniLM-L12-v2 (configurable)

Version History

See CHANGELOG for release history.

🤝 Contributing

Contributions are welcome! Please visit the GitHub repository to:

Report bugs
Request features
Submit pull requests
Join discussions

📝 License

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

📧 Support

Documentation: https://github.com/fsvxavier/nexs-mcp/tree/main/docs
Issues: https://github.com/fsvxavier/nexs-mcp/issues
Discussions: https://github.com/fsvxavier/nexs-mcp/discussions

🔗 Alternative Installation Methods

If NPM doesn't work for you, try these alternatives:

Go Install

go install github.com/fsvxavier/nexs-mcp/cmd/[email protected]

Homebrew (macOS/Linux)

brew tap fsvxavier/nexs-mcp
brew install nexs-mcp

Docker

docker pull fsvxavier/nexs-mcp:latest
docker run -v $(pwd)/data:/app/data fsvxavier/nexs-mcp:latest

Build from Source

git clone https://github.com/fsvxavier/nexs-mcp.git
cd nexs-mcp
make build
./bin/nexs-mcp

⬆ Back to Top

Made with ❤️ by the NEXS MCP team