Metadata-Version: 2.4
Name: pyke-mcp
Version: 0.1.1
Summary: MCP server for Pyke logic programming engine
Author: David Xu
License: MIT
License-File: LICENSE
Keywords: inference-engine,logic-programming,mcp,pyke
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Requires-Dist: pyke>=1.1.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Pyke MCP Server

An MCP (Model Context Protocol) server for the [Pyke](https://pyke.sourceforge.net/) logic programming inference engine. This server enables LLMs to perform logical reasoning through knowledge bases with facts, rules, and queries.

## Features

- **Fact Management**: Add ground truth facts to the knowledge base
- **Rule Definition**: Define inference rules using forward chaining
- **Query Execution**: Check if facts can be derived from the knowledge base
- **Goal Proving**: Find all variable bindings that satisfy a goal
- **Session Management**: Support multiple independent knowledge bases
- **Logic-LLM Compatible**: Load programs in Logic-LLM format

## Installation

### Using pip

```bash
pip install git+https://github.com/evertrol/pyke3 pyke-mcp
```

### From source

```bash
git clone https://github.com/NewJerseyStyle/pyke-mcp.git
cd pyke-mcp
pip install -e .
```

### Dependencies

- Python 3.10+
- `mcp>=1.2.0`
- `pyke>=1.1.1` (Install from source by `pip install git+https://github.com/evertrol/pyke3` but the package name is `pyke` not `pyke3`)

## Quick Start

### Running the Server

```bash
# Using the installed command
pyke-mcp

# Or using Python
python -m pyke_mcp.server
```

### Configuration for Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "pyke": {
      "command": "pyke-mcp"
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "pyke": {
      "command": "pyke-mcp"
    }
  }
}
```

Or with explicit Python path:

```json
{
  "mcpServers": {
    "pyke": {
      "command": "python",
      "args": ["-m", "pyke_mcp.server"]
    }
  }
}
```

## Available Tools

### `add_fact`
Add a fact to the knowledge base.

```
Predicate(arg1, arg2, ...)
```

**Examples:**
- `Human(Socrates, True)` - Socrates is human
- `Parent(John, Mary)` - John is a parent of Mary

### `add_rule`
Add an inference rule using forward chaining.

```
Premise >>> Conclusion
Premise1 && Premise2 >>> Conclusion
```

**Examples:**
- `Human($x, True) >>> Mortal($x, True)` - All humans are mortal
- `Parent($x, $y) && Parent($y, $z) >>> Grandparent($x, $z)` - Grandparent relationship

### `add_facts_and_rules`
Bulk add multiple facts and rules at once.

### `query`
Check if a specific fact can be derived.

```
Predicate(Subject, ExpectedValue)
```

**Example:**
- `Mortal(Socrates, True)` - "Is Socrates mortal?"

### `prove_goal`
Find all variable bindings that satisfy a goal.

**Examples:**
- `Mortal($who, True)` - "Who is mortal?"
- `Parent($parent, Mary)` - "Who are Mary's parents?"

### `get_program`
Display the current knowledge base contents.

### `clear_program`
Clear all facts and rules from the session.

### `load_logic_program`
Load a complete logic program from formatted text (Logic-LLM compatible).

### `list_sessions`
List all active sessions.

### `delete_session`
Delete a specific session.

## Usage Examples

### Classic Syllogism

```
# Add facts
add_fact("Human(Socrates, True)")
add_fact("Human(Plato, True)")

# Add rule
add_rule("Human($x, True) >>> Mortal($x, True)")

# Query
query("Mortal(Socrates, True)")
# Result: True, Match: True

# Find all mortals
prove_goal("Mortal($who, True)")
# Bindings: who=Socrates, who=Plato
```

### Family Relationships

```
# Facts
add_fact("Parent(Alice, Bob)")
add_fact("Parent(Bob, Charlie)")
add_fact("Parent(Bob, Diana)")

# Rules
add_rule("Parent($x, $y) && Parent($y, $z) >>> Grandparent($x, $z)")

# Find Alice's grandchildren
prove_goal("Grandparent(Alice, $grandchild)")
# Bindings: grandchild=Charlie, grandchild=Diana
```

### Loading a Complete Program

```python
program = """
Predicates:
Human(x, bool)
Mortal(x, bool)

Facts:
Human(Socrates, True)
Human(Aristotle, True)

Rules:
Human($x, True) >>> Mortal($x, True)

Query:
Mortal(Socrates, True)
"""

load_logic_program(program)
```

## Logic Program Format

The server accepts programs in the Logic-LLM format:

```
Predicates:
PredicateName(arg1_type, arg2_type, ...)

Facts:
PredicateName(value1, value2, ...)

Rules:
Premise($var, value) >>> Conclusion($var, value)
Premise1($x, val) && Premise2($x, val) >>> Conclusion($x, val)

Query:
PredicateName(subject, expected_value)
```

### Syntax Rules

1. **Facts**: Ground assertions without variables
   - `Human(Socrates, True)`
   - `Age(John, 30)`

2. **Rules**: Implications with variables (prefixed with `$`)
   - `Human($x, True) >>> Mortal($x, True)`
   - Multiple premises joined with `&&`

3. **Variables**: Prefixed with `$`
   - `$x`, `$person`, `$value`

4. **Values**: Can be boolean (`True`/`False`) or strings
   - `True`, `False`, `Socrates`, `Blue`

## Session Management

The server supports multiple independent sessions:

```python
# Create/use a session
add_fact("Human(Socrates, True)", session_id="philosophy")

# Use a different session
add_fact("Cat(Whiskers, True)", session_id="animals")

# List sessions
list_sessions()

# Delete a session
delete_session("philosophy")
```

## Error Handling

The server provides clear error messages for:
- Invalid fact/rule syntax
- Query execution failures
- Missing Pyke installation
- Session not found

## Based On

- [Pyke Knowledge Engine](https://pyke.sourceforge.net/)
- [Logic-LLM](https://github.com/teacherpeterpan/Logic-LLM) - Pyke solver implementation
- [clingo-mcp](https://github.com/newjerseystyle/clingo-mcp) - MCP server interface reference

## License

MIT License
