README.md•8.11 kB
# MCP Ecosystem by vpursuit
[](https://github.com/vpursuit/model-context-lab/actions/workflows/npm-publish.yml)
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`](https://www.npmjs.com/package/@vpursuit/swipl-mcp-server)
- **Documentation**: [products/swipl-mcp-server](./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](./plugins/server/core) |
| `@vpursuit/mcp-server-prolog` | SWI-Prolog integration | [plugins/server/prolog](./plugins/server/prolog) |
| `@vpursuit/mcp-server-roots` | Filesystem roots discovery | [plugins/server/roots](./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:
```typescript
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
```bash
# 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
```bash
# 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](./products/swipl-mcp-server/README.md#installation)** — Complete setup for all MCP clients
- **[Configuration](./products/swipl-mcp-server/README.md#configuration)** — Filesystem roots, environment variables
- **[Troubleshooting](./products/swipl-mcp-server/README.md#troubleshooting)** — Common issues and debug mode
- **[Features Reference](./products/swipl-mcp-server/docs/features.md)** — Detailed prompts, resources, and tools documentation
- **[Examples](./products/swipl-mcp-server/docs/examples.md)** — Copy-paste usage examples
- **[Architecture](./products/swipl-mcp-server/docs/architecture.md)** — Components, modes, and wire protocol
- **[Lifecycle](./products/swipl-mcp-server/docs/lifecycle.md)** — Server lifecycle, state, and persistence patterns
- **[Deployment](./products/swipl-mcp-server/docs/deployment.md)** — Release, packaging, and install from source
### Monorepo Documentation
- **[Publishing Guide](./PUBLISHING.md)** — How to publish packages to npm
- **[Contributing](./CONTRIBUTING.md)** — Development workflow and guidelines
- **[Security](./SECURITY.md)** — Security policies and vulnerability reporting
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Code of conduct
- Development workflow
- Testing requirements
- Pull request process
- Coding standards
For security issues, see [SECURITY.md](./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](./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](./SECURITY.md) for complete security documentation and reporting.
## 📄 License
All packages in this monorepo are licensed under **BSD-3-Clause**.
See [LICENSE](./LICENSE) file for details.
## 🔗 Links
- **GitHub**: [vpursuit/model-context-lab](https://github.com/vpursuit/model-context-lab)
- **NPM Organization**: [@vpursuit](https://www.npmjs.com/org/vpursuit)
- **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **SWI-Prolog**: [swi-prolog.org](https://www.swi-prolog.org)
## Getting Started
**For end users**: Install the complete MCP server
```bash
npx @vpursuit/swipl-mcp-server
```
**For monorepo developers**: Work with the plugin system
```bash
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
```bash
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](https://github.com/vpursuit/model-context-lab/issues) or see our [documentation](./products/swipl-mcp-server#readme).