MCPM

You have an MCP server setup that connects your local development workspace with multiple large language model providers, while remembering context, watching file changes, and exposing a practical interface for tool execution. This guide walks you through practical usage, installation steps, configuration options, and common troubleshooting so you can start querying LLMs, manage memories, and keep your context up to date.

How to use

You use the MCP server by running it locally or by using the HTTP REST wrapper to expose endpoints that your MCP clients can call. Start the server, pick a provider, and send queries that leverage persistent memories and file-change context. You can browse your project directory, let the memory store prune old entries automatically, and inject file-change context into your conversations with the LLM.

How to install

Prerequisites you need on your system before installing: Python 3.10 or higher and a working Python toolchain, plus a compatible package manager for installing dependencies. You should also have a modern terminal to run commands and a project directory you want the MCP server to monitor.

Follow these concrete steps to install and run the MCP server and its optional REST wrapper.

# Step 1: Set up your project directory
# Replace with your actual path
PROJECT_DIR="/path/to/your/project"

# Step 2: Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Step 3: Install dependencies
pip install -r requirements.txt

# Step 4: Run the MCP backend directly (stdio mode) using a config file
python mcp_backend.py fgd_config.yaml

# Step 5: Or run the HTTP REST wrapper (FastAPI) if desired
python server.py

# Step 6: If you want a GUI experience, start the GUI as well
python gui_main_pro.py

Configuration

Configure your MCP server to manage memory, define LLM providers, set timeouts, and control how many memories are kept. The configuration governs how the server watches files, how context is built, and how retry logic behaves for remote API calls.

Key configuration sections you will typically adjust include the watch directory, memory storage path, per-provider timeouts, and LRU pruning settings to bound memory usage.

watch_dir: "/path/to/your/project"    # Directory to monitor
memory_file: ".fgd_memory.json"        # Memory storage file
log_file: "fgd_server.log"             # Log output file
context_limit: 20                      # Max context items to keep
max_memory_entries: 1000               # NEW: Max memories before LRU pruning

llm:
  default_provider: "grok"             # Default LLM provider
  providers:
    grok:
      model: "grok-3"
      base_url: "https://api.x.ai/v1"
      timeout: 30                      # NEW: Configurable timeout (seconds)
    openai:
      model: "gpt-4o-mini"
      base_url: "https://api.openai.com/v1"
      timeout: 60                      # NEW: Longer for complex queries
    claude:
      model: "claude-3-5-sonnet"
      base_url: "https://api.anthropic.com/v1"
      timeout: 90
    ollama:
      model: "llama3"
      base_url: "http://localhost:11434/v1"
      timeout: 120

New in this setup is the per-provider timeout controls and the automatic memory pruning threshold. The memory store uses an LRU strategy to prune memories when the maximum limit is exceeded.

Troubleshooting

If the MCP server fails to start or you see connectivity issues, verify your API keys are present, your watch directory has proper permissions, and the port used for the HTTP wrapper (if enabled) is available. Review logs to identify the exact error and confirm the backend is actively reading from the configured watch directory.

Common issues include memory not persisting after a restart, file watcher not detecting changes, and LLM queries timing out. Ensure file locking is active to prevent races, and confirm per-provider timeouts are appropriate for your model speeds.

Security and best practices

Do not expose sensitive API keys in public configurations. Use environment variables to supply keys for Grok, OpenAI, Anthropic, and local models, and restrict access to the REST API if you enable the HTTP wrapper. Enable memory file permissions to 600 to restrict access, and use atomic write patterns to avoid data loss during crashes.

Rotate API keys regularly and monitor for unusual access patterns. When running the MCP server in production, enable proper TLS for external communications and apply rate limiting on REST endpoints.

Examples and notes

You can start the HTTP REST server and query memory and LLM tools from MCP clients or scripts that support the MCP protocol. The HTTP wrapper exposes endpoints at the configured host and port, while the stdio backend can be driven by local MCP clients.

Tools and endpoints overview

This server supports a suite of tools that enable file and memory management and LLM querying. Tools can read and write files, browse directories, compute diffs, and perform LLM queries with context injection.

REST and CLI start commands

You can run the CLI or GUI to start the MCP server or the REST wrapper. The self-contained commands shown below start the services directly.

# Start the MCP backend in stdio mode using a config file
python mcp_backend.py fgd_config.yaml

# Start the FastAPI REST wrapper
python server.py

# Start the GUI in pro mode (if you prefer a graphical interface)
python gui_main_pro.py

Available tools

list_directory

Browse files with gitignore awareness and pattern matching to limit results.

read_file

Read file contents with encoding detection and size validation.

write_file

Write files with automatic backup and atomic write guarantees.

edit_file

Edit existing files with diff previews and approval workflow.

git_diff

Show uncommitted changes using unified diff format.

git_commit

Commit changes with AI-generated or configured messages.

git_log

View commit history with configurable depth.

llm_query

Query an LLM with context injection and retry logic across providers.

remember

Store information in persistent memory with automatic LRU pruning.

recall

Retrieve stored memories with access tracking.

search_in_files

Search project files with query patterns.

list_files

List files matching a pattern within the project.