TSAP MCP Server

A Model Context Protocol (MCP) implementation of Text Search and Analysis Processing (TSAP) server for code intelligence and text analysis.

Table of Contents

• TSAP MCP Server
  • Overview
  • Project Components
  • Features
  • Installation
  • Usage
  • Architecture
  • Development
  • Contributing
  • License

Overview

TSAP MCP Server is an implementation of the Model Context Protocol (MCP) standard that provides advanced text search, processing, and analysis capabilities. It operates as a standalone server exposing a wide range of functionality through the MCP interface, making it compatible with Claude Desktop and other MCP-compatible clients.

Built on the MCP Python SDK and utilizing a diverse set of specialized libraries, this server empowers AI assistants with rich capabilities for working with text, code, and document analysis through standardized interfaces.

Project Components

This project consists of three major components that work together:

1. tsap: The core Text Search and Analysis Processing system providing fundamental capabilities for:

   • Code and text search
   • Document analysis
   • Pattern extraction
   • Data processing
   • Evolutionary algorithms
   • Storage and caching

   This component implements the core functionality and business logic of the system.

2. toolapi: An internal API system within tsap that:

   • Defines the tool interaction protocol
   • Handles tool request/response lifecycle
   • Manages tool registration and discovery
   • Provides client libraries for tool consumption

   The toolapi serves as the original API layer for programmatic access to TSAP capabilities.

3. tsap_mcp: The Model Context Protocol adapter layer that:

   • Wraps the core TSAP functionality in MCP-compatible interfaces
   • Maps TSAP tools to MCP tool functions
   • Implements resource handlers for MCP URI patterns
   • Provides MCP prompt templates
   • Serves as a bridge between TSAP and Claude Desktop (or other MCP clients)

Together, these components create a powerful system where the core TSAP functionality is exposed through a standardized MCP interface, making it seamlessly integratable with Claude Desktop and other AI assistants that support the Model Context Protocol.

Features

• MCP Protocol Implementation: Fully compliant with the Model Context Protocol standard for AI tooling.

• Search Capabilities:

  • Text search with regex support, case sensitivity options, and path filtering
  • Code search using ripgrep with pattern matching and file filtering
  • Semantic search using embedding models from Nomic and sentence-transformers

• Processing Tools:

  • Text normalization and transformation
  • Pattern-based data extraction
  • Document structure analysis

• Analysis Tools:

  • Code quality and structure analysis
  • Text content analysis
  • Document profiling and metadata extraction

• Visualization Tools:

  • Data visualization using matplotlib
  • Network visualization with networkx

• Resource Access:

  • File content access with path-based retrieval
  • Project structure information
  • Configuration management
  • Semantic corpus management

• Claude Desktop Integration:

  • Seamless integration with Claude Desktop through the MCP protocol

Installation

Prerequisites

• Python 3.13 or higher
• ripgrep installed on your system (for code search functionality)

From Source

# Clone the repository
git clone https://github.com/your-org/tsap-mcp.git
cd tsap-mcp

# Install the package
pip install -e .

# For all optional dependencies (visualization, semantic search, etc.)
pip install -e ".[all]"

Claude Desktop Integration

To install the server for use with Claude Desktop:

tsap-mcp install --desktop

This will register the server with Claude Desktop, making it available for use in conversations.

Usage

Running the Server

# Run with default settings (localhost:8000)
tsap-mcp run

# Specify host and port
tsap-mcp run --host 0.0.0.0 --port 9000

# Enable auto-reload for development
tsap-mcp run --reload

# Disable adapter layer
tsap-mcp run --no-adapter

Server Information

# Show basic server information
tsap-mcp info

# Show all registered components (tools, resources, prompts)
tsap-mcp info --components

Command-Line Options

The server supports various command-line options:

tsap-mcp run [-H HOST] [-p PORT] [--reload] [--no-adapter]
tsap-mcp info [--components]
tsap-mcp test [--compatibility]
tsap-mcp install [--desktop] [--system]

Environment Variables

The server behavior can be configured using the following environment variables:

• TSAP_HOST: Host to bind (default: 127.0.0.1)
• TSAP_PORT: Port to bind (default: 8000)
• TSAP_LOG_LEVEL: Logging level (default: INFO)
• TSAP_PERFORMANCE_MODE: Performance mode (balanced, speed, accuracy)
• TSAP_CACHE_ENABLED: Enable cache (default: true)
• TSAP_DEBUG: Enable debug mode (default: false)

Architecture

TSAP MCP Server follows a modular architecture organized around the core components:

src/
├── tsap/                  # Core TSAP implementation
│   ├── __init__.py        # Package initialization
│   ├── server.py          # Main server implementation
│   ├── cli.py             # Command-line interface
│   ├── config.py          # Configuration management
│   ├── main.py            # Main entry point
│   ├── api/               # API layer 
│   ├── analysis/          # Text and code analysis
│   ├── core/              # Core functionality
│   ├── project/           # Project management
│   ├── storage/           # Storage utilities
│   ├── utils/             # Utility functions
│   ├── toolapi/           # Tool API protocol implementation
│   │   ├── __init__.py    # Package initialization
│   │   ├── handler.py     # Tool request handling
│   │   ├── models.py      # Data models
│   │   ├── protocol.py    # Protocol definition
│   │   └── client/        # Client libraries
│   └── ...                # Other TSAP components
│
├── tsap_mcp/              # MCP adapter layer
│   ├── __init__.py        # Package initialization
│   ├── server.py          # MCP server implementation
│   ├── cli.py             # Command-line interface
│   ├── adapter.py         # Adapter for original TSAP
│   ├── tool_map.py        # Tool mapping utilities
│   ├── lifespan.py        # Server lifecycle management
│   ├── tools/             # MCP tool implementations
│   │   ├── search.py      # Search tools
│   │   ├── processing.py  # Text processing tools
│   │   ├── analysis.py    # Analysis tools
│   │   ├── visualization.py # Visualization tools
│   │   └── composite.py   # Composite tools
│   ├── resources/         # MCP resource implementations
│   │   ├── files.py       # File access resources
│   │   ├── project.py     # Project structure resources
│   │   ├── config.py      # Configuration resources
│   │   └── semantic.py    # Semantic corpus resources
│   ├── prompts/           # MCP prompt implementations
│   └── adapters/          # Protocol adapters
│
├── scripts/               # Utility scripts
└── tests/                 # Test suite

Data Flow

The data flow in the system follows this pattern:

1. An MCP client (such as Claude Desktop) makes a request to the tsap_mcp server
2. The tsap_mcp adapter layer translates the MCP request to the appropriate tsap operation
3. The tsap core system processes the request, potentially using its toolapi subsystem
4. Results are transformed back into MCP-compatible responses by tsap_mcp
5. The MCP client receives and processes the response

MCP Components

The server implements three MCP component types:

1. Tools: Functions that can be called to perform specific actions
2. Resources: Data access patterns through URI-based interfaces
3. Prompts: Reusable templates for common interactions

Development

Development Environment Setup

# Clone the repository
git clone https://github.com/your-org/tsap-mcp.git
cd tsap-mcp

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Running in Development Mode

# Run with auto-reload
tsap-mcp run --reload

MCP Inspector

For development and debugging, you can use the MCP Inspector:

pip install mcp[cli]
mcp dev src/tsap_mcp/server.py

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

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