Model Context Lab

🚀 MCP Ecosystem by vpursuit

This monorepo offers Model Context Protocol (MCP) packages and products, enabling AI assistants to interact with SWI - Prolog, filesystems, and an extensible plugin system.

🚀 Quick Start

For End Users

Install the complete MCP server:

npx @vpursuit/swipl-mcp-server

For Monorepo Developers

Work with the plugin system:

git clone https://github.com/vpursuit/model-context-lab.git
cd model-context-lab
npm install
npm run build

For Contributors

Set up the development environment:

git clone https://github.com/vpursuit/model-context-lab.git
cd model-context-lab
npm install
npm run build
npm test

✨ Features

SWI - Prolog MCP Server

• Full - featured MCP server with Prolog knowledge base integration: A MCP server that allows tools - enabled LLMs to work directly with SWI‑Prolog. It supports loading Prolog files, adding/removing facts and rules, listing symbols, and running queries in two modes: deterministic pagination and true engine backtracking.
  • NPM: @vpursuit/swipl-mcp-server
  • Documentation: products/swipl-mcp-server
  • Quick Start: npx @vpursuit/swipl-mcp-server
• Feature Highlights:
  • Knowledge base management (load, assert, retract, dump)
  • Two query modes: standard (call_nth/2) and engine (true backtracking)
  • Expert Prolog assistance prompts (e.g., solving logic puzzles)
  • Comprehensive security sandboxing
  • Dynamic filesystem roots
  • Plugin - based architecture

📦 Installation

Prerequisites

• Node.js ≥ 20.0.0
• SWI - Prolog (for testing Prolog integration)
• npm ≥ 9.0.0

Setup

# Clone repository
git clone https://github.com/vpursuit/model-context-lab.git
cd model-context-lab

# Install all dependencies
npm install

# Build all packages
npm run build

# Run all tests
npm test

Working with Packages

# Build specific package
npm run build -w plugins/server/core

# Test specific package
npm test -w plugins/server/prolog

# Clean all build artifacts
npm run clean

💻 Usage Examples

Plugin System for Developers

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { loadPlugins } from '@vpursuit/mcp-server-core';
import { plugin as prologPlugin } from '@vpursuit/mcp-server-prolog';
import { plugin as rootsPlugin } from '@vpursuit/mcp-server-roots';

const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Load plugins
await loadPlugins(server, [prologPlugin, rootsPlugin]);

📚 Documentation

Product Documentation (swipl - mcp - server)

• Installation & Setup — Complete setup for all MCP clients
• Configuration — Filesystem roots, environment variables
• Troubleshooting — Common issues and debug mode
• Features Reference — Detailed prompts, resources, and tools documentation
• Examples — Copy - paste usage examples
• Architecture — Components, modes, and wire protocol
• Lifecycle — Server lifecycle, state, and persistence patterns
• Deployment — Release, packaging, and install from source

Monorepo Documentation

• Publishing Guide — How to publish packages to npm
• Contributing — Development workflow and guidelines
• Security — Security policies and vulnerability reporting

🔧 Technical Details

Architecture

This repository follows a products/plugins architecture:

• Products (products/): Published packages that end - users install (e.g., @vpursuit/swipl-mcp-server)
• Plugins (plugins/): Internal, reusable components bundled within products (not published separately)

Internal Plugin System

The MCP server is built with a modular plugin architecture. These plugins are internal dependencies bundled into the main product:

Note: These plugins are marked as private in their package.json and are bundled into @vpursuit/swipl-mcp-server. They are not published separately to npm.

Repository Structure

This is a monorepo managed with npm workspaces. Each package can be developed, tested, and published independently.

model-context-lab/
├── products/
│   └── swipl-mcp-server/    # Main MCP server (published to npm)
├── plugins/
│   └── server/
│       ├── core/            # Plugin system foundation (internal)
│       ├── prolog/          # SWI-Prolog integration (internal)
│       └── roots/           # Filesystem roots discovery (internal)
├── docs/                    # Monorepo-level documentation
├── .archive/                # Historical strategy documents
└── package.json             # Workspace configuration

Each package has:

• Own package.json with independent versioning
• Own README.md with complete documentation
• Own LICENSE (BSD - 3 - Clause)
• Own test suite

📄 License

All packages in this monorepo are licensed under BSD - 3 - Clause. See LICENSE file for details.

🔗 Links

• GitHub: vpursuit/model-context-lab
• NPM Organization: @vpursuit
• Model Context Protocol: modelcontextprotocol.io
• SWI - Prolog: swi - prolog.org

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of conduct
• Development workflow
• Testing requirements
• Pull request process
• Coding standards

For security issues, see SECURITY.md.

Publishing

Only products are published to npm under the @vpursuit scope:

• Products (e.g., @vpursuit/swipl-mcp-server) are published to npm for end users
• Plugins are internal dependencies bundled within products (not published separately)
• Releases use semantic versioning: v<version> (e.g., v3.0.0)
• Automated publishing via GitHub Actions
• Supply chain security: All packages published with npm provenance attestation
• See PUBLISHING.md for complete details

Security

All packages implement security best practices:

• File path restrictions
• Dangerous predicate blocking
• Pre - execution validation
• Timeout protection
• Module isolation

Supply Chain Security:

• Published with npm provenance attestation for build transparency
• OIDC - based publishing (no long - lived tokens)
• Cryptographically signed packages via Sigstore

See SECURITY.md for complete security documentation and reporting.

Questions? Open an issue or see our documentation.