Ocean Breezer Casefiles MCP Server

A Model Context Protocol (MCP) server implementation for exploring and analyzing Ocean Breezer casefiles using the Zep Cloud SDK. This server allows language models to interact with casefile data, search through episodes, and explore relationships through a standardized interface.

Features

• Casefile Exploration: Access and browse through Ocean Breezer casefiles with detailed indexing
• Episode Management: Retrieve detailed episode information and recent casefiles using Zep Cloud SDK
• Advanced Search: Comprehensive search across casefile content with configurable ranking strategies
• Entity Analysis: Explore entities, relationships, and facts extracted from casefiles
• Group-Based Access: Hardcoded to work with Ocean Breezer group for consistent data access
• Seamless MCP Integration: Works with Claude Desktop and other AI tools supporting MCP

Installation & Usage

Using npx (recommended)

The easiest way to use this package is through npx:

npx ocean-breezer-casefiles-mcp-server

Using with Claude Desktop

To use with Claude Desktop:

1. Open Claude Desktop
2. Enable the MCP feature in settings
3. Add the server configuration to your claude_desktop_config.json:

   {
     "mcpServers": {
       "ocean-breezer-casefiles": {
         "command": "npx",
         "args": [
           "-y",
           "ocean-breezer-casefiles-mcp-server@latest",
           "--zep-api-key",
           "YOUR_ZEP_API_KEY",
           "--mongo-uri", 
           "mongodb://username:password@host:port/database",
           "--db-name",
           "your-database-name"
         ]
       }
     }
   }

4. Restart Claude Desktop
5. Ask Claude to search memories, explore knowledge graphs, and analyze relationships

Global Installation

You can install the package globally using:

npm install -g ocean-breezer-casefiles-mcp-server

Then run:

ocean-breezer-casefiles-mcp-server

Manual Installation

1. Clone this repository
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Start the server:

node dist/index.js

MCP Integration

This server implements the Model Context Protocol, allowing language models to:

1. Search and explore Ocean Breezer casefiles using various strategies
2. Find specific entities and relationships in casefile data
3. Access detailed information about episodes and their content
4. Navigate through casefile indexes and specific pages
5. Retrieve recent casefiles and episode details

Available Tools (8 Total)

The server provides a comprehensive set of tools for working with Ocean Breezer casefiles:

🔍 Search Tools (2)

1. search_casefile_content: Performs comprehensive search across casefile content, extracted entities, and relationships. Returns relevant emails and entities based on the search query.

2. advanced_casefile_search: Executes advanced search with configurable ranking strategies, relationship context, and filtering options. Provides more control over search results than the basic search.

📁 Casefile Tools (3)

3. get_casefile_index: Get the casefile index which contains short summaries of all pages (emails) in a casefile along with their corresponding page numbers.

4. get_casefile_pages_by_number: Get the full detailed content of specific pages (emails) from a casefile by page number.

5. get_casefile_page_by_uuid: Get detailed information about a specific casefile page (email) by UUID.

📝 Episode Tools (2)

6. get_recent_casefiles: Retrieve the most recent episodes (casefiles) for the Ocean Breezer group using the Zep Cloud SDK.

7. get_episode_details: Get detailed information about a specific episode by UUID using the Zep Cloud SDK.

🎯 Entity Tools (1)

8. get_entity_details: Get detailed information about a specific entity extracted from casefile pages, including its properties, relationships, and connected facts.

Usage Examples

Basic Casefile Search

// Search across casefile content
{
  "tool": "search_casefile_content",
  "arguments": {
    "query": "safety protocols",
    "search_focus": "comprehensive",
    "max_results": 15
  }
}

Advanced Casefile Search

// Search with specific ranking strategy
{
  "tool": "advanced_casefile_search",
  "arguments": {
    "query": "incident reports",
    "ranking_strategy": "most_accurate",
    "search_focus": "emails_only",
    "max_results": 20
  }
}

Get Recent Casefiles

// Retrieve recent casefiles from Ocean Breezer group
{
  "tool": "get_recent_casefiles",
  "arguments": {
    "lastn": 10
  }
}

Get Episode Details

// Get detailed information about a specific episode
{
  "tool": "get_episode_details",
  "arguments": {
    "episode_uuid": "episode-uuid-here"
  }
}

Browse Casefile Content

// Get casefile index first
{
  "tool": "get_casefile_index",
  "arguments": {
    "casefile_id": "casefile-id-here",
    "limit": 20
  }
}

// Then get specific pages
{
  "tool": "get_casefile_pages_by_number",
  "arguments": {
    "casefile_id": "casefile-id-here",
    "pages": [1, 2, 3]
  }
}

Architecture

This server is built on:

• Zep Cloud SDK: For accessing Ocean Breezer casefiles and episodes
• Model Context Protocol (MCP): Standardized AI tool integration
• TypeScript: Type-safe development
• MongoDB: For casefile indexing and page management
• Advanced Search: Multiple ranking strategies and search focus options

Development

For development, you can run the server directly using ts-node:

npm run dev

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.

About Ocean Breezer

Ocean Breezer is a comprehensive casefile management system that enables AI applications to access, search, and analyze casefile data through the Zep Cloud platform. This MCP server provides a bridge between Ocean Breezer's casefile capabilities and AI language models through standardized tool interfaces, allowing for efficient exploration and analysis of casefile content.