MCP Prolog Server with trealla

This project implements an MCP (Multi-Component Protocol) server that allows clients, potentially driven by LLMs, to interact with a Prolog knowledge base. It uses Node.js, Express, and the trealla library to provide a Trealla Prolog environment.

Features

• Assert new facts and rules into the Prolog database.
• Query the Prolog database and retrieve variable bindings.
• Retract specific clauses from the database.
• List all user-defined clauses currently in the database.
• Powered by trealla, a WASM-based Trealla Prolog interpreter.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Project Structure

• server.js: The main Node.js Express server application.
• gemini_prolog_client.py: A Python client script demonstrating how to interact with the server.
• package.json: Defines project dependencies and scripts.
• README.md: This file.

Setup

1. Clone the repository (if you haven't already):

   git clone https://github.com/Helvia/mcp-trealla.git
   cd mcp-trealla

2. Install Node.js dependencies:

   npm install

3. Install Python client dependencies (for gemini_prolog_client.py): It's recommended to use a virtual environment for Python projects.

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   pip install requests google-generativeai

   You will also need to set the GEMINI_API_KEY environment variable for the Python client to work:

   export GEMINI_API_KEY='your_actual_gemini_api_key'

Running the Server

Start the Node.js server:

npm start

The server will typically run on http://localhost:3000.

API Endpoints

All API endpoints are session-specific and require a sessionId path parameter. The sessionId can be any unique string generated by the client to identify a distinct Prolog session.

The server exposes the following HTTP endpoints:

1. Assert Clause

• Endpoint: POST /session/:sessionId/prolog/assert
• Description: Adds a single Prolog clause (fact, rule, or directive) to the knowledge base for the specified session.
• Request Body: JSON object

  {
      "clause": "father(john, mary)."
  }

  • clause: A string containing a single complete Prolog clause. It should end with a period. Directives (e.g., :- dynamic(predicate/arity).) are processed by the server to modify the Prolog environment for the session. Facts and rules are asserted into the database.
• Success Response (200 OK):

  {
      "success": true,
      "message": "Clause asserted: father(john, mary)."
  }

• Error Response (e.g., 400 Bad Request):

  {
      "success": false,
      "message": "A Prolog clause to assert is required...",
      "error": "Clause is required"
  }

2. Query Knowledge Base

• Endpoint: POST /session/:sessionId/prolog/query
• Description: Executes a Prolog query within the specified session and returns solutions.
• Request Body: JSON object

  {
      "query": "father(X, mary)"
  }

  • query: A string containing a valid Prolog query. The server will automatically add a trailing period if one is not present.
• Success Response (200 OK):

  {
      "success": true,
      "answers": [
          { "X": "john" }
      ]
  }

  Returns an empty array [] for answers if the query fails or has no solutions (for non-ground queries). For ground queries that succeed, answers will be [{}].
• Error Response (e.g., 400 Bad Request):

  {
      "success": false,
      "message": "A Prolog query is required...",
      "error": "Query is required"
  }

3. List Clauses

• Endpoint: GET /session/:sessionId/prolog/listing
• Description: Retrieves a textual listing of all user-defined clauses in the current session's knowledge base. System-internal predicates are filtered out.
• Request Body: None
• Success Response (200 OK):

  {
      "success": true,
      "listing": "father(john,mary).\nlikes(jane,apples).\nmother(jane,mary).\nancestor(A,B) :-\n    mother(A,B).\nancestor(A,B) :-\n    father(A,B)."
  }

  If no user-defined clauses exist, listing will be an empty string or contain only directives like :- dynamic.

4. Retract Clause

• Endpoint: POST /session/:sessionId/prolog/retract
• Description: Removes the first clause in the specified session's knowledge base that unifies with the provided term.
• Request Body: JSON object

  {
      "clause": "likes(jane,apples)"
  }

  • clause: A string representing a Prolog term (fact or rule head). The server will automatically add a trailing period if one is not present. Variables can be used if the intent is to retract the first matching instance.
• Success Response (200 OK, if a clause was retracted):

  {
      "success": true,
      "message": "Clause retracted: likes(jane,apples)"
  }

• Not Found Response (404 Not Found, if no matching clause was found):

  {
      "success": false,
      "message": "No matching clause found for retract: likes(jane,apples)"
  }

• Error Response (e.g., 400 Bad Request):

  {
      "success": false,
      "message": "A Prolog clause to retract is required...",
      "error": "Clause (Prolog term string) for retract is required"
  }

Running the Python Client

The gemini_prolog_client.py script provides an interactive command-line interface to communicate with the Prolog server using natural language. It leverages the Google Gemini API to translate your commands into Prolog actions (assert, retract, list, query).

1. Ensure the MCP Prolog server is running (see "Running the Server").
2. Ensure Python dependencies are installed (see "Setup" section), including requests and google-generativeai.
3. Set your Gemini API Key: The client requires the GEMINI_API_KEY environment variable to be set.

   export GEMINI_API_KEY='your_actual_gemini_api_key'

   Replace 'your_actual_gemini_api_key' with your valid key.
4. Run the client:

   python3 gemini_prolog_client.py

   You will be prompted with Your message >. You can then type natural language commands like:
   • "Assert father(john, mary) and mother(lisa, john)."
   • "List the knowledge base."
   • "Retract father(john, mary)."
   • "Retract all facts."
   • "Who is mary's father?" (Query functionality relies on Gemini's interpretation to form a Prolog query)
   • Type quit to exit the client.

The client will print debug information showing Gemini's interpretation of your command and the server's responses.

Development Notes

• The server uses trealla which runs Trealla Prolog in a WebAssembly environment.
• The Python client (gemini_prolog_client.py) uses the Google Gemini API to interpret natural language commands and translate them into Prolog actions for the server. It demonstrates a more advanced integration than simple placeholder functions.