contexis-mcp-server

contexis-cmp/contexis-mcp-server

3.1

If you are the rightful owner of contexis-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Contexis MCP Server is a Model Context Protocol server designed to facilitate interaction between Large Language Models (LLMs) and Contexis projects, providing capabilities for code analysis, exploration, and development assistance.

Contexis MCP Server

A Model Context Protocol (MCP) server for Contexis projects that allows Large Language Models (LLMs) to interact with Contexis projects through the MCP standard. This server provides capabilities for code analysis, exploration, and development assistance.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants and Large Language Models (LLMs) to interact with external tools, data sources, and systems in a structured and secure way. MCP provides a standardized interface for:

  • Tool Integration: Connecting AI assistants to external APIs, databases, and services
  • Data Access: Allowing AI to read and analyze files, documents, and structured data
  • Action Execution: Enabling AI to perform actions like file operations, API calls, and system commands
  • Context Management: Providing AI with relevant context and information for better responses

Why MCP for Contexis?

Contexis projects contain rich information about AI agents, contexts, prompts, tools, and memory that can be valuable for AI assistants. The MCP server bridges this gap by:

  • Exposing Contexis Components: Making contexts, prompts, tools, and memory accessible to AI assistants
  • Standardized Interface: Using the MCP protocol for consistent and reliable communication
  • Security: Providing controlled access to project resources with proper validation
  • Extensibility: Supporting custom capabilities and integrations

Features

šŸ”§ Core Capabilities

  • Context Management: List and retrieve Contexis contexts with full metadata
  • Prompt Management: Access, render, and manage prompt templates with variable substitution
  • Tool Integration: List, inspect, and execute Contexis tools and integrations
  • File System Access: Search, read, and analyze project files with security validation
  • Memory Access: Search and retrieve memory items from Contexis knowledge bases

šŸš€ Technical Features

  • RESTful API: HTTP-based MCP implementation for easy integration
  • Health Monitoring: Built-in health check and readiness endpoints
  • Structured Logging: Comprehensive logging with configurable levels
  • Configuration Management: Flexible configuration via YAML files and environment variables
  • Security: Path validation, project isolation, and optional authentication

šŸ› ļø Development Features

  • Modular Architecture: Extensible capability system for custom integrations
  • Comprehensive Testing: Unit tests, integration tests, and coverage reporting
  • Docker Support: Multi-stage container builds with security best practices
  • Development Tools: Makefile automation, linting, and development scripts
  • Documentation: Complete API documentation and usage examples

šŸ”’ Security & Reliability

  • Path Validation: Prevents directory traversal attacks
  • Project Isolation: Restricts file access to project boundaries
  • Error Handling: Comprehensive error reporting and graceful degradation
  • Graceful Shutdown: Proper cleanup and resource management
  • Non-root Execution: Container runs as non-privileged user

Installation

Prerequisites

  • Go 1.21 or later
  • A Contexis project directory

Build

# Clone the repository
git clone <repository-url>
cd contexis-mcp-server

# Build the server
go build -o contexis-mcp-server main.go

# Or install dependencies and build
go mod tidy
go build -o contexis-mcp-server main.go

Configuration

The server can be configured using a YAML configuration file or environment variables.

Configuration File

Create a mcp-config.yaml file in your project root:

# Server settings
host: "localhost"
port: 8080

# Logging
log_level: "info"

# Project directories (relative to project root)
contexts_dir: "contexts"
memory_dir: "memory"
prompts_dir: "prompts"
tools_dir: "tools"
tests_dir: "tests"

# Enabled capabilities
capabilities:
  - "contexts"
  - "prompts"
  - "tools"
  - "filesystem"
  - "memory"

Environment Variables

You can also configure the server using environment variables:

export MCP_HOST=localhost
export MCP_PORT=8080
export MCP_LOG_LEVEL=info
export MCP_API_KEY=your-api-key

Usage

Starting the Server

# Start with default configuration
./contexis-mcp-server

# Start with custom project root
./contexis-mcp-server --project-root /path/to/contexis/project

# Start with custom config file
./contexis-mcp-server --config /path/to/config.yaml

# Enable verbose logging
./contexis-mcp-server --verbose

API Endpoints

Health Check
curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}
List Capabilities
curl http://localhost:8080/capabilities

Response:

{
  "capabilities": [
    {
      "name": "contexts",
      "description": "Manage Contexis contexts",
      "methods": ["list", "get"]
    },
    {
      "name": "prompts",
      "description": "Manage Contexis prompts",
      "methods": ["list", "get", "render"]
    }
  ]
}
MCP Requests
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-123",
    "capability": "contexts",
    "method": "list",
    "params": {}
  }'

MCP Capabilities

Contexts

Manage Contexis contexts.

Methods
  • list: List all available contexts
  • get: Get a specific context by name
Examples
# List all contexts
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "contexts",
    "method": "list"
  }'

# Get specific context
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "contexts",
    "method": "get",
    "params": {
      "name": "SupportBot"
    }
  }'

Prompts

Manage Contexis prompt templates.

Methods
  • list: List prompts for a component
  • get: Get a specific prompt
  • render: Render a prompt with variables (TODO)
Examples
# List prompts for a component
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "prompts",
    "method": "list",
    "params": {
      "component": "SupportBot"
    }
  }'

# Get specific prompt
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "prompts",
    "method": "get",
    "params": {
      "component": "SupportBot",
      "name": "agent_response"
    }
  }'

Tools

Manage Contexis tools.

Methods
  • list: List tools for a component
  • get: Get a specific tool
  • execute: Execute a tool (TODO)
Examples
# List tools for a component
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "tools",
    "method": "list",
    "params": {
      "component": "SupportBot"
    }
  }'

Filesystem

Access project files.

Methods
  • search: Search for files by name
  • read: Read file content
  • list: List directory contents (TODO)
Examples
# Search for files
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "filesystem",
    "method": "search",
    "params": {
      "query": "main.go"
    }
  }'

# Read file content
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "filesystem",
    "method": "read",
    "params": {
      "path": "src/main.go"
    }
  }'

Memory

Access Contexis memory (TODO).

Methods
  • search: Search memory items
  • get: Get specific memory item
  • list: List memory items

Integration with LLMs

Claude Desktop Integration

Claude Desktop is the official desktop application for Claude AI that supports MCP servers. This integration allows Claude to directly access and interact with your Contexis projects, providing powerful AI assistance for development and analysis.

šŸš€ Quick Start

  1. Install Claude Desktop from Anthropic's website

  2. Build the MCP Server:

    cd contexis-mcp-server
make build

  3. Configure Claude Desktop:

    • Open Claude Desktop
    • Go to Settings ā†’ Model Context Protocol
    • Add a new server configuration

  4. Add Server Configuration:

    {
  "mcpServers": {
    "contexis": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": [
        "--project-root", "/path/to/your/contexis/project",
        "--verbose"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
šŸŽÆ What Claude Can Do

With the Contexis MCP server, Claude can:

  • Analyze Contexts: Review and understand your AI agent configurations
  • Examine Prompts: Read and suggest improvements to prompt templates
  • Inspect Tools: Understand available tools and their capabilities
  • Search Code: Find and analyze relevant files in your project
  • Provide Guidance: Offer suggestions for improving your Contexis setup
  • Debug Issues: Help troubleshoot configuration problems
šŸ’” Example Conversations

Analyzing a Context:

Claude, can you analyze the SupportBot context and suggest improvements?

Reviewing Prompts:

Show me the prompt templates for the CustomerDocs component and suggest optimizations.

Finding Files:

Search for all files related to memory configuration in the project.

Code Review:

Review the main.go file and suggest any improvements for error handling.
āš™ļø Advanced Configuration

Custom Configuration File:

{
  "mcpServers": {
    "contexis": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": [
        "--config", "/path/to/custom/mcp-config.yaml",
        "--project-root", "/path/to/your/contexis/project"
      ],
      "env": {
        "MCP_LOG_LEVEL": "debug",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

Multiple Project Support:

{
  "mcpServers": {
    "contexis-main": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": ["--project-root", "/path/to/main/project"]
    },
    "contexis-dev": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": ["--project-root", "/path/to/dev/project"]
    }
  }
}
šŸ”§ Troubleshooting

Server Not Starting:

  • Check that the binary path is correct and executable
  • Verify the project root path exists
  • Enable verbose logging: --verbose

Claude Can't Connect:

  • Ensure the server is running: curl http://localhost:8080/health
  • Check Claude Desktop logs for connection errors
  • Verify the configuration JSON syntax

Permission Issues:

  • Make sure the binary has execute permissions: chmod +x contexis-mcp-server
  • Check file permissions in the project directory
šŸ“Š Best Practices
  1. Use Absolute Paths: Always use absolute paths in your configuration
  2. Enable Logging: Use --verbose for debugging
  3. Test First: Verify the server works before adding to Claude Desktop
  4. Keep Updated: Regularly update both Claude Desktop and the MCP server
  5. Secure Access: Use API keys for production environments

Other MCP Clients

The server implements a RESTful MCP interface that can be used with any MCP client that supports HTTP transport.

Development

Project Structure

contexis-mcp-server/
ā”œā”€ā”€ main.go                 # Main entry point
ā”œā”€ā”€ go.mod                  # Go module file
ā”œā”€ā”€ go.sum                  # Go dependencies
ā”œā”€ā”€ mcp-config.yaml         # Sample configuration
ā”œā”€ā”€ README.md              # This file
ā””ā”€ā”€ internal/
    ā”œā”€ā”€ config/            # Configuration management
    ā”œā”€ā”€ server/            # HTTP server implementation
    ā”œā”€ā”€ capabilities/      # MCP capabilities
    ā””ā”€ā”€ project/           # Contexis project operations

Adding New Capabilities

  1. Create a new handler in internal/capabilities/handlers.go
  2. Register the handler in internal/capabilities/capabilities.go
  3. Add the capability to the capabilities list
  4. Update the configuration schema if needed

Testing

# Run tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test
go test ./internal/project -v

Security Considerations

  • The server runs on localhost by default
  • File access is restricted to the project root directory
  • API key authentication can be enabled for additional security
  • All file operations are validated to prevent directory traversal

Troubleshooting

Common Issues

  1. Port already in use: Change the port in configuration
  2. Project not found: Ensure the project root path is correct
  3. Permission denied: Check file permissions in the project directory

Logs

Enable verbose logging to see detailed information:

./contexis-mcp-server --verbose

Health Check

Use the health endpoint to verify the server is running:

curl http://localhost:8080/health

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

License

This project is licensed under the MIT License - see the file for details.

Support

For support and questions:

  • Create an issue on GitHub
  • Check the Contexis documentation
  • Join the Contexis community