MindPort MCP Server

A high-performance Model Context Protocol (MCP) server built in TypeScript/Node.js that provides optimized storage and search capabilities for AI systems. Designed for seamless integration with Claude Desktop and other MCP clients.

Features

Advanced Search: Token-efficient fuzzy search, regex patterns, and grep-like functionality
SQLite Storage: Reliable, lightweight database with domain isolation
Smart Organization: Domain-based resource management with tag filtering
AI-Optimized: Designed specifically for Claude Desktop/Code integration
High Performance: Fast search and retrieval optimized for large datasets
Comprehensive Testing: 76+ tests covering all functionality
Prompt Templates: Store and render reusable prompt templates with variables
Modern Web Interface: Professional dashboard for browsing and managing resources

Installation

NPM Package

npm install -g mindport-mcp
mindport --help

From Source

git clone https://github.com/mindport-ai/mcp-mindport.git
cd mcp-mindport
npm install
npm run build

Production Deployment

# Install globally
npm install -g mindport-mcp

# Or run with npx
npx mindport-mcp

# Start web interface
npx mindport-mcp --web

The installation automatically:

Installs all dependencies
Sets up SQLite database
Configures default settings
Creates necessary directories

Quick Start

Development Mode

# Install dependencies
npm install

# Start MCP server (for Claude Desktop)
npm run dev

# Start web interface (in new terminal)
npm run web
# Visit http://localhost:3001

Production Mode

# Build for production
npm run build

# Start production server
npm start

# Start web interface
npm run web:start

Testing

# Run comprehensive test suite
npm test

# Run tests once
npm run test:run

# Run with coverage
npm run test:coverage

Production Deployment

Publishing to NPM

# Prepare for release
npm run build
npm run test:run

# Publish to NPM
npm publish

# Install globally from NPM
npm install -g mindport-mcp

Docker Deployment

# Build Docker image
docker build -t mindport-mcp .

# Run in container
docker run -d -p 3001:3001 \
  -v ~/.config/mindport:/root/.config/mindport \
  mindport-mcp

Production Server Setup

# Install globally
npm install -g mindport-mcp

# Create systemd service (Linux)
sudo tee /etc/systemd/system/mindport.service << EOF
[Unit]
Description=MindPort MCP Server
After=network.target

[Service]
Type=simple
User=mindport
WorkingDirectory=/opt/mindport
ExecStart=/usr/bin/node /usr/local/bin/mindport-mcp
Restart=always
Environment=NODE_ENV=production
Environment=MCP_MINDPORT_LOG=/var/log/mindport.log

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable mindport
sudo systemctl start mindport

Configuration

The server automatically creates configuration at ~/.config/mindport/config.yaml:

server:
  host: "localhost"
  port: 8080

storage:
  path: "~/.config/mindport/data/storage.db"

search:
  index_path: "~/.config/mindport/data/search"

domain:
  default_domain: "default"

Environment Variables

# Disable logging (recommended for MCP)
export MCP_MINDPORT_LOG=discard

# Set custom domain
export MCP_MINDPORT_DOMAIN=my-project

# Custom storage path
export MCP_MINDPORT_STORE_PATH=/path/to/storage.db

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mindport": {
      "command": "npx",
      "args": ["mindport-mcp"],
      "env": {
        "MCP_MINDPORT_LOG": "discard"
      }
    }
  }
}

Restart Claude Desktop to activate MindPort.

Available MCP Tools

Resource Management

`store_resource`

Store content with metadata and tags ``json5 { id: "api-docs-v1", name: "API Documentation", description: "REST API endpoints and authentication", content: "GET /users - Retrieve users...", tags: ["api", "documentation", "rest"], mimeType: "text/markdown" } ``

`get_resource`

Retrieve specific resource by ID ``json5 { id: "api-docs-v1" } ``

`list_resources`

List resources in current domain ``json5 { limit: 20, offset: 0 } ``

Search & Discovery

`search_resources`

Fast, token-efficient fuzzy search ``json5 { query: "API authentication methods", limit: 10 } ``

`advanced_search`

Complex queries with tag filtering ``json5 { query: "database design", tags: ["sql", "performance"], exactTags: true } ``

`grep`

Regex pattern matching (like ripgrep) ``json5 { pattern: "function\\s+\\w+\\(" } ``

`find`

Find resources by name patterns ``json5 { pattern: "^API.*" } ``

Domain Management

`list_domains`

List all available domains ``json5 {} ``

`create_domain`

Create new domain context ``json5 { name: "frontend-project", description: "Frontend development resources" } ``

`switch_domain`

Change current domain ``json5 { domain: "frontend-project" } ``

`domain_stats`

Get domain statistics and top tags ``json5 { domain: "frontend-project" } // optional ``

Prompt Templates

`store_prompt`

Store reusable prompt templates ``json5 { id: "code-review", name: "Code Review Prompt", template: "Review this {{language}} code for {{focus}}:\n\n`{{language}}\n{{code}}\n`", variables: ["language", "focus", "code"] } ``

`list_prompts`

List available prompt templates ``json5 {} ``

`get_prompt`

Retrieve and render prompts with variables ``json5 { id: "code-review", variables: { "language": "TypeScript", "focus": "performance", "code": "const result = await fetch('/api');" } } ``

Architecture

┌─────────────────┐
│  Claude Desktop │ (MCP Client)
│                 │
└─────────┬───────┘
          │ JSON-RPC 2.0 via stdio
          │
┌─────────▼───────┐
│   MCP Server    │ (TypeScript/Node.js)
│                 │
├─────────────────┤
│ Domain Manager  │ (Project isolation)
│                 │  
├─────────────────┤
│ Fuse.js Search  │ (Fuzzy + pattern search)
│                 │
├─────────────────┤
│ SQLite Storage  │ (Resources + prompts)
│                 │
└─────────────────┘

Key Components

TypeScript/Node.js: Modern, maintainable codebase
SQLite: Reliable embedded database with ACID transactions
Fuse.js: Advanced fuzzy search with scoring and highlighting
Official MCP SDK: Anthropic's official Model Context Protocol implementation
Commander.js: Robust CLI interface with comprehensive options
Vitest: Modern testing framework with 76+ comprehensive tests

Token Optimization

MindPort is specifically optimized for AI interactions:

Compact Responses: Minimal formatting, maximum information density
Smart Truncation: Long content is intelligently summarized
Relevance Scoring: Results ranked by relevance to save tokens
Configurable Limits: Control response size with limit parameters
Context-Aware: Domain isolation reduces noise in search results

Search Capabilities

Fuzzy Search

# Finds "JavaScript Tutorial" even with typos
search_resources: "javascrpt tutorial"

Regex Patterns

# Find all function definitions
grep: "function\\s+\\w+\\("

# Find resources starting with "API"
find: "^API.*"

Tag-Based Filtering

# Exact tag matching
advanced_search: { query: "auth", tags: ["security"], exactTags: true }

# Partial tag matching  
advanced_search: { query: "auth", tags: ["sec"], exactTags: false }

Performance

Tested with 100+ resources:

Storage: < 10s for 100 resources
Indexing: < 1s for search index updates
Search: < 100ms for fuzzy search queries
Grep: < 100ms for regex pattern matching
Pagination: < 500ms for large result sets

Testing

Comprehensive test suite with 76 tests covering:

Storage Layer (17 tests): SQLite operations, CRUD, domain isolation
Search Engine (30 tests): Fuzzy search, patterns, grep, tag filtering
MCP Server (25 tests): All tools, error handling, tool schemas
Integration (4 tests): End-to-end workflows, performance, multi-domain

# Run all tests
npm test

# Run specific test suites
npm test storage
npm test search  
npm test server
npm test integration

Advanced Usage

Multi-Domain Workflow

# Create project domains
create_domain: { name: "frontend", description: "Frontend code and docs" }
create_domain: { name: "backend", description: "API and database" }

# Switch contexts
switch_domain: { domain: "frontend" }

# Store domain-specific resources
store_resource: { 
  name: "React Component", 
  content: "const Button = ...",
  tags: ["react", "component"]
}

Template-Driven Prompts

# Store template
store_prompt: {
  id: "bug-report",
  template: "Bug in {{component}}:\n**Expected:** {{expected}}\n**Actual:** {{actual}}"
}

# Use template
get_prompt: {
  id: "bug-report", 
  variables: { 
    component: "Login Form",
    expected: "User logged in",
    actual: "Error 401"
  }
}

Contributing

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass: npm run test:run
Submit a pull request

License

MIT License - see LICENSE file for details.

---

Built for Claude Desktop | Optimized for AI Workflows | TypeScript + SQLite + Vitest

MindPort MCP Server