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.