# MCP Context Hub
Local MCP server (Node.js + TypeScript) for context optimization, RAG memory, semantic cache, and sub-MCP proxy. Designed to run on a machine with GPU (RTX 3060 Ti) + Ollama, acting as a single MCP endpoint for Claude.
## Architecture
```
Claude (Remote)
|
HTTP POST/GET/DELETE + Bearer Token
|
+-----------v-----------+
| Express (:3100) |
| Auth + IP Allowlist |
+-----------+-----------+
|
+-----------v-----------+
| McpServer (SDK v1) |
| |
| Tools: |
| context_pack |
| memory_search |
| memory_upsert |
| context_compress |
| proxy_call |
+-+------+------+-----+-+
| | | |
v v v v
Ollama SQLite Cache ProxyMgr
Client Vector LRU (stdio
(chat Store +TTL sub-MCP)
+embed +FTS5
+fallback)
```
## Features
- **context_pack** — Combines semantic + text search, deduplication, and LLM synthesis into a structured context bundle (summary, facts, next actions)
- **memory_search** — Semantic similarity search over stored documents using vector embeddings
- **memory_upsert** — Store documents with automatic chunking, embedding, and indexing
- **context_compress** — Compress text into bullets, JSON, steps, or summary format to reduce token usage
- **proxy_call** — Call tools on sub-MCP servers (e.g., filesystem) with optional post-processing (summarize, compress)
## Requirements
- Node.js >= 20
- [Ollama](https://ollama.ai) with the following models:
- `llama3.1:8b-instruct-q4_K_M` (primary chat)
- `qwen2.5:7b-instruct-q4_K_M` (fallback chat)
- `nomic-embed-text:v1.5` (embeddings, 768 dims)
## Quick Start
```bash
# 1. Clone and install
git clone https://github.com/DiegoNogueiraDev/mcp-context-hub.git
cd mcp-context-hub
npm install
# 2. Pull Ollama models
ollama pull llama3.1:8b-instruct-q4_K_M
ollama pull qwen2.5:7b-instruct-q4_K_M
ollama pull nomic-embed-text:v1.5
# 3. Configure environment
cp .env.example .env
# Edit .env and set MCP_AUTH_TOKEN to a secure random value
# 4. Start the server
npm run dev
```
Or use the setup script:
```bash
chmod +x scripts/setup.sh
./scripts/setup.sh
npm run dev
```
## Usage
### Health Check
```bash
curl http://localhost:3100/health
# {"status":"healthy","timestamp":"..."}
```
### MCP Protocol
The server uses Streamable HTTP transport at `/mcp`. Initialize a session first:
```bash
# Initialize session
curl -X POST http://localhost:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer <your-token>" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": { "name": "my-client", "version": "1.0.0" }
},
"id": 1
}'
```
Then call tools using the `mcp-session-id` header from the response:
```bash
# Store a document
curl -X POST http://localhost:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "memory_upsert",
"arguments": {
"document_id": "my-doc",
"content": "Your document text here...",
"scope": "project",
"tags": ["example"]
}
},
"id": 2
}'
# Search memories
curl -X POST http://localhost:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "memory_search",
"arguments": {
"query": "your search query",
"top_k": 5
}
},
"id": 3
}'
```
### Sub-MCP Proxy
Configure sub-MCP servers via the `PROXY_SERVERS` environment variable:
```bash
PROXY_SERVERS='{"filesystem":{"command":"node","args":["node_modules/@modelcontextprotocol/server-filesystem/dist/index.js","/tmp"]}}' npm run dev
```
Then call tools on them via `proxy_call`:
```json
{
"name": "proxy_call",
"arguments": {
"server": "filesystem",
"tool": "read_file",
"arguments": { "path": "/tmp/example.txt" },
"post_process": "none"
}
}
```
## Configuration
All settings via environment variables (see `.env.example`):
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_AUTH_TOKEN` | | Bearer token for authentication |
| `MCP_ALLOWED_IPS` | `127.0.0.1,::1` | Comma-separated allowed IPs |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama API URL |
| `PRIMARY_MODEL` | `llama3.1:8b-instruct-q4_K_M` | Primary chat model |
| `FALLBACK_MODEL` | `qwen2.5:7b-instruct-q4_K_M` | Fallback chat model |
| `EMBEDDING_MODEL` | `nomic-embed-text:v1.5` | Embedding model |
| `PORT` | `3100` | Server port |
| `HOST` | `0.0.0.0` | Server host |
| `DB_PATH` | `./data/context-hub.db` | SQLite database path |
| `CACHE_TTL_MS` | `300000` | Cache TTL (5 minutes) |
| `CACHE_MAX_ENTRIES` | `100` | Max cache entries |
| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |
| `PROXY_SERVERS` | `{}` | Sub-MCP server configs (JSON) |
## Commands
```bash
npm run dev # Start dev server (HTTP on :3100)
npm run dev:stdio # Start in stdio mode (for local MCP testing)
npm run build # Compile TypeScript
npm start # Run compiled output
npm test # Run tests (31 tests, 6 files)
npm run typecheck # Type-check without emitting
npm run health # Run health check script
```
## Project Structure
```
src/
config.ts # Environment configuration
index.ts # Entry point + graceful shutdown
db/
connection.ts # SQLite singleton (WAL mode)
migrations.ts # Table definitions (documents, chunks, FTS5, audit)
cosine.ts # Cosine similarity + embedding serialization
server/
mcp-server.ts # McpServer setup + tool registration
transport.ts # Express + Streamable HTTP transport
session.ts # Session management
middleware/
auth.ts # Bearer token validation
ip-allowlist.ts # IP restriction
audit.ts # Tool call logging
tools/
schemas.ts # Zod schemas for all tools
context-pack.ts # context_pack implementation
memory-search.ts # memory_search implementation
memory-upsert.ts # memory_upsert implementation
context-compress.ts # context_compress implementation
proxy-call.ts # proxy_call implementation
services/
ollama-client.ts # Ollama API (chat + embed + fallback)
sqlite-vector-store.ts # Vector store (SQLite + brute-force cosine)
text-search.ts # FTS5 full-text search
chunker.ts # Recursive text splitter
dedup.ts # Content hashing + Jaccard dedup
semantic-cache.ts # LRU + TTL in-memory cache
proxy-manager.ts # Sub-MCP stdio connections
utils/
logger.ts # Pino structured logging
metrics.ts # In-memory call metrics
retry.ts # Exponential backoff retry
tokens.ts # Token estimation
types/
index.ts # Type re-exports
ollama.ts # Ollama API types
vector-store.ts # VectorStore interface
tests/
unit/ # cosine, chunker, dedup, cache
integration/ # sqlite vector store
e2e/ # Express server
```
## Tech Stack
- **Runtime**: Node.js 20, TypeScript
- **MCP SDK**: `@modelcontextprotocol/sdk` v1.26
- **HTTP**: Express v5 + Streamable HTTP transport
- **Database**: SQLite (`better-sqlite3`) with WAL mode, FTS5
- **Embeddings**: Ollama `nomic-embed-text:v1.5` (768 dimensions)
- **Chat**: Ollama with automatic model fallback
- **Validation**: Zod v4
- **Logging**: Pino
- **Testing**: Vitest
## License
MIT
