AsterMind-ELM MCP Server

A local Model Context Protocol server for training small text classifiers with
Extreme Learning Machines (ELMs). It supports in-memory inference and optional
SurrealDB persistence, prediction monitoring, and vector storage.

Is it useful?

Yes, for focused classification tasks where data must stay under your control
and rapid retraining matters. Good candidates include intent routing, spam or
content categorization, support-ticket triage, and lightweight labeling aids.

It is not a general semantic-search model or a production ML platform. The
generate_embedding tool exposes a trained ELM's task-specific hidden features;
it does not use a pretrained language model and should not be described as a
semantic embedding without evaluation on the intended corpus.

Capabilities

• Train multi-class text classifiers from labeled examples.
• Predict labels and return ranked confidence scores.
• Generate model-specific hidden-feature vectors.
• Keep multiple models in memory and inspect their metadata.
• Optionally store and reload versioned models and datasets in SurrealDB.
• Optionally log predictions and calculate accuracy, latency, label counts, a
  confusion matrix, and distribution drift.
• Store arbitrary equal-dimension vectors and search them with cosine
  similarity.

The server exposes 16 MCP tools:

• Core: train_classifier, predict, generate_embedding, list_models,
  delete_model, save_model
• Persistence: store_model_persistent, load_model_persistent,
  list_model_versions, store_training_dataset, load_training_dataset
• Monitoring: get_model_metrics, get_confusion_matrix, detect_drift
• Vector storage: store_embeddings, search_similar

save_model returns an in-memory summary. Use store_model_persistent when a
model must survive a restart.

Requirements

• Node.js 18 or newer
• SurrealDB only when persistence is enabled

Install, build, and test

npm ci
npm run build
npm test

Additional commands:

npm run test:watch
npm run test:coverage
npm run watch

Coverage is enforced for the production TypeScript at 80% statements, 65%
branches, 80% functions, and 80% lines. CI runs the locked dependency set on
Node.js 18, 20, and 22.

MCP configuration

Build first, then point an MCP client at the compiled stdio entry point:

{
  "mcpServers": {
    "astermind-elm": {
      "command": "node",
      "args": ["/absolute/path/to/astermind-elm-mcp/build/index.js"]
    }
  }
}

The server writes protocol messages to stdout and diagnostics to stderr.

Minimal workflow

Call train_classifier:

{
  "model_id": "sentiment",
  "training_data": [
    { "text": "excellent purchase", "label": "positive" },
    { "text": "love this product", "label": "positive" },
    { "text": "terrible purchase", "label": "negative" },
    { "text": "hate this product", "label": "negative" }
  ],
  "config": {
    "hiddenUnits": 128,
    "activation": "relu"
  }
}

Then call predict:

{
  "model_id": "sentiment",
  "text": "I love this purchase",
  "top_k": 2
}

Use representative training and held-out evaluation data. Training success is
not evidence that the classifier generalizes.

Optional SurrealDB persistence

The sample credentials below are for disposable local development only. Do not
use them on a reachable database.

surreal start --log info --user root --pass root memory
npm run build
npm run init-db

Enable persistence in the MCP server environment:

{
  "ENABLE_PERSISTENCE": "true",
  "LOG_PREDICTIONS": "false",
  "SURREALDB_URL": "ws://127.0.0.1:8000/rpc",
  "SURREALDB_NAMESPACE": "astermind",
  "SURREALDB_DATABASE": "development",
  "SURREALDB_USERNAME": "root",
  "SURREALDB_PASSWORD": "root"
}

Persisted models are loaded explicitly with load_model_persistent; they are
not automatically loaded after restart. If global prediction logging is on,
"log_prediction": false disables it for an individual request.

Prediction records contain the input text. Enabling logging therefore changes
the privacy boundary: protect the database, credentials, backups, and access
logs appropriately. “Local” only means local when both the MCP client and the
configured database endpoint are local.

Monitoring semantics

• Accuracy and confusion matrices require predictions logged with
  ground_truth.
• Drift compares predicted-label distributions with KL divergence; it does not
  measure accuracy degradation or causal drift.
• detect_drift returns status: "insufficient_data" and null drift fields if
  either comparison window has no samples.
• Monitoring queries currently materialize matching prediction rows in the
  server, so benchmark and redesign aggregation before high-volume use.

Test layers

• Unit tests cover validation, model lifecycle, encoding, persistence queries,
  metrics, drift, and vector search.
• Handler tests cover all 16 tool-dispatch paths and model serialization.
• A real stdio MCP test starts the compiled child server and exercises protocol
  discovery, training, prediction, and error responses.
• SurrealDB integration tests are opt-in and require an initialized disposable
  database:

SURREALDB_TEST_URL=ws://127.0.0.1:8000/rpc \
SURREALDB_TEST_NAMESPACE=astermind_test \
SURREALDB_TEST_DATABASE=integration \
npx vitest run tests/surrealdb.integration.test.ts

Current limitations

• There is no built-in train/validation split, evaluation dataset tool, model
  selection, calibration analysis, or batch prediction API.
• Confidence scores should not be treated as calibrated probabilities without
  measurement.
• Model records store serialized weights but are not encrypted by this server.
• Database schema evolution is handled by the initialization script, not a
  versioned migration system.
• Vector search uses a database cosine-similarity query without a declared
  vector index; it is not an approximate-nearest-neighbor service.

These constraints make the project best suited to local prototypes, personal
automation, and bounded internal workloads until workload-specific evaluation,
security review, and operational testing are complete.

Project structure

src/index.ts                         MCP schemas, server, and tool handlers
src/model-manager.ts                 In-memory model lifecycle
src/tool-validation.ts               Runtime input validation
src/text-features.ts                 Shared normalized text encoding
src/persistence/surrealdb-client.ts  Persistence and monitoring operations
src/scripts/init-db.ts               SurrealDB schema initialization
tests/                               Unit, handler, stdio, and DB integration tests

See PERSISTENCE_GUIDE.md for persistence examples. The
proposal and completion-summary documents in the repository are historical and
are not evidence of the current release quality.

License

MIT