Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dicklesworthstone/tsap_mcp_server


https://github.com/dicklesworthstone/tsap_mcp_server

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

          
# 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](#tsap-mcp-server)

  - [Overview](#overview)

  - [Project Components](#project-components)

  - [Features](#features)

  - [Installation](#installation)

  - [Usage](#usage)

  - [Architecture](#architecture)

  - [Development](#development)

  - [Contributing](#contributing)

  - [License](#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



```bash

# 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:



```bash

tsap-mcp install --desktop

```



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



## Usage



### Running the Server



```bash

# 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



```bash

# 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



```bash

# 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



```bash

# Run with auto-reload

tsap-mcp run --reload

```



### MCP Inspector



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



```bash

pip install mcp[cli]

mcp dev src/tsap_mcp/server.py

```



## Contributing



Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.