MCP Thought Server

🚀 MCP Thought Server Usage Instructions

The MCP Thought Server is a powerful tool designed to handle user requests, maintain context, generate thought results, and format outputs. This guide provides detailed instructions on installation, operation, error handling, and more.

🚀 Quick Start

📦 Installation

To install all the necessary dependencies, run the following command in the root directory of the project:

npm install

▶️ Starting the Server

There are three common ways to start the server:

Method 1: Start with npx

Run the following command directly to start the server:

npx ts-node src/index.ts

Method 2: Build and Start

First, build the project, then start the built file:

npm run build
npm start

Method 3: Start with a Docker Container (see the Docker Support section below)

⚙️ Configuring Environment Variables

The following are the environment variables required for the server to run and their descriptions:

❗ Error Handling and Common Issues

1. "Original draft X not found" Error

This error indicates that the previous draft record cannot be retrieved. Please ensure the following:

• The database file path (through MCP_SQLITE_PATH or the default path data/mcp-thought-server.sqlite) is correct.
• The server process has write permissions for the directory and file where the database file is located.
• If you suspect the database file is corrupted, you can try deleting the old .sqlite file to rebuild a new empty database. Note that this operation will result in the loss of historical data.

2. LLM Coherence Check Issues

If you enable the coherence check, please ensure the following configurations are correct:

• COHERENCE_API_KEY: Contains a valid API key.
• COHERENCE_CHECK_MODEL: Specifies the model ID that supports structured JSON output.
• Ensure that the external LLM service is running properly.

To disable the coherence check, you can delete or comment out the relevant environment variable configurations.

3. Low Confidence Score

Possible reasons include:

• The output content of the AI does not match the context semantics (check the semantic similarity scoring section).
• The coherence check is enabled, but the model output is inconsistent.
• The context parameter provided to the tool is insufficient or vaguely defined.

4. Failure to Download Embedded Models

Please ensure that you have an internet connection when running the server for the first time to download the necessary embedded models. Also, check the permissions of the cache directory:

npm run download-models

🏗️ Architecture Overview

The MCP Thought Server is built on the following main components:

• Input Processing Module: Responsible for receiving and parsing user requests.
• Context Manager: Maintains the context information of the current thinking process.
• Inference Engine: Generates thinking results based on the context and evaluates confidence.
• Output Adapter: Formats the inference results into the specified output format.

🐳 Docker Support

1. Building the Image

Run the following command in the root directory of the project to build the Docker image:

docker build -t mcp-thought-server .

2. Running the Container

Use the following command to start the MCP Thought Server container:

Basic Startup

docker run --name mcp-thought-container -it mcp-thought-server

Configuring Environment Variables and Binding Ports

docker run --name mcp-thought-container \
    -e LOG_LEVEL=info \
    -e TRANSPORT=http \
    -p 3000:3000 \
    -it mcp-thought-server

3. Stopping and Deleting the Container

Stop the running container:

docker stop mcp-thought-container

Delete the stopped container:

docker rm mcp-thought-container

📎 Appendix: Environment Variable Reference

The following are all the environment variables supported by the server and their detailed descriptions:

If you have any other questions or need further assistance, please feel free to refer to the project documentation or contact the maintenance team.