MCP Ecosystem by vpursuit

This monorepo contains Model Context Protocol (MCP) packages and products that enable AI assistants to work with SWI-Prolog, filesystems, and extensible plugin systems.

Products

SWI-Prolog MCP Server

Full-featured MCP server with Prolog knowledge base integration

A MCP server that lets tools-enabled LLMs work directly with SWI‑Prolog. It supports loading Prolog files, adding/removing facts and rules, listing symbols, and running queries with 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

Features:

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

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:

Plugin	Description	Location
`@vpursuit/mcp-server-core`	Plugin system foundation	plugins/server/core
`@vpursuit/mcp-server-prolog`	SWI-Prolog integration	plugins/server/prolog
`@vpursuit/mcp-server-roots`	Filesystem roots discovery	plugins/server/roots

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.

Plugin System for Developers

If you're developing within this monorepo, you can use the plugin system directly:

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]);

📂 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

🔧 Development

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

Package Development

Each package supports:

npm run build - TypeScript compilation
npm run clean - Remove build artifacts
npm test - Run Vitest tests
npm run test:watch - Watch mode for tests

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

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.

📄 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

Getting Started

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

Questions? Open an issue or see our documentation.

SWI-Prolog