@ebowwa/claudecodehistory 1.1.1 → 1.2.0

package/example/README.md

@@ -0,0 +1,79 @@
+# Claude Code History MCP Server - Example
+
+This is an example MCP server that demonstrates how to use the `@ebowwa/claudecodehistory` library to create an MCP server for Claude Code conversation history.
+
+## About This Example
+
+This example shows how to:
+- Use the `ClaudeCodeHistoryService` class from the library
+- Wrap it in an MCP server using the Model Context Protocol SDK
+- Expose the service's functionality as MCP tools
+
+## Features
+
+This MCP server provides **4 powerful tools** for exploring your Claude Code conversation history:
+
+### 1. `list_projects`
+Discover all projects with Claude Code conversation history.
+
+### 2. `list_sessions`
+List conversation sessions for exploration and filtering.
+
+### 3. `get_conversation_history`
+Retrieve paginated conversation history with smart filtering.
+
+### 4. `search_conversations`
+Search across all conversation content by keywords.
+
+## Quick Start
+
+```bash
+# From the example directory
+cd example
+
+# Install dependencies (uses bun)
+bun install
+
+# Run directly
+bun src/index.ts
+```
+
+## Usage with MCP Clients
+
+Add the following configuration to your MCP client (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "claude-code-history": {
+      "command": "bun",
+      "args": ["/path/to/claude-code-history-mcp/example/src/index.ts"]
+    }
+  }
+}
+```
+
+## Development
+
+- **Runtime:** `bun` (no build step required)
+- **TypeScript:** Executed directly via bun
+- **Hot reload:** `bun --hot src/index.ts`
+
+## Library Dependency
+
+This example imports from `@ebowwa/claudecodehistory` (the parent package):
+
+```typescript
+import { ClaudeCodeHistoryService } from '@ebowwa/claudecodehistory';
+```
+
+The service provides all the core functionality for accessing Claude Code history:
+
+- `getConversationHistory()` - Get paginated conversation history
+- `searchConversations()` - Search by content
+- `listProjects()` - List all projects
+- `listSessions()` - List sessions with filters
+
+## License
+
+MIT

package/example/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claude-code-history-mcp-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "claude-code-history-mcp": "src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "start": "bun src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ebowwa/claudecodehistory": "file:..",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.4",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "history",
+    "conversation",
+    "example",
+    "typescript",
+    "bun"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/example/src/index.ts

@@ -0,0 +1,233 @@
+#!/usr/bin/env bun
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClaudeCodeHistoryService } from '@ebowwa/claudecodehistory';
+
+const server = new Server(
+  {
+    name: 'claude-code-history-mcp',
+    version: '1.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+const historyService = new ClaudeCodeHistoryService();
+
+// Helper function to create response
+const createResponse = (data: any) => ({ // eslint-disable-line @typescript-eslint/no-explicit-any
+  content: [{
+    type: 'text',
+    text: JSON.stringify(data),
+  }],
+});
+
+// Define available tools (ordered by recommended workflow)
+const tools: Tool[] = [
+  {
+    name: 'list_projects',
+    description: 'List all projects with Claude Code conversation history (start here to explore available data)',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'list_sessions',
+    description: 'List conversation sessions for a project or date range (use after list_projects to find specific sessions)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: {
+          type: 'string',
+          description: 'Filter by specific project path (optional)',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Start date in ISO format (optional)',
+        },
+        endDate: {
+          type: 'string',
+          description: 'End date in ISO format (optional)',
+        },
+        timezone: {
+          type: 'string',
+          description: 'Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_conversation_history',
+    description: 'Get paginated conversation history (use after exploring with list_projects/list_sessions for targeted data)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'Specific session ID to get history for (optional)',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Start date in ISO format (optional)',
+        },
+        endDate: {
+          type: 'string',
+          description: 'End date in ISO format (optional)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of conversations to return (default: 20)',
+          default: 20,
+        },
+        offset: {
+          type: 'number',
+          description: 'Number of conversations to skip for pagination (default: 0)',
+          default: 0,
+        },
+        messageTypes: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: ['user', 'assistant', 'system', 'result']
+          },
+          description: 'Filter by specific message types. Defaults to ["user"] to reduce data volume. Use ["user", "assistant"] to include Claude responses.',
+          default: ['user']
+        },
+        timezone: {
+          type: 'string',
+          description: 'Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.',
+        },
+      },
+    },
+  },
+  {
+    name: 'search_conversations',
+    description: 'Search through conversation history by content (useful for finding specific topics across all conversations)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query to find in conversation content',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results to return (default: 30)',
+          default: 30,
+        },
+        projectPath: {
+          type: 'string',
+          description: 'Filter by specific project path (optional)',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Start date in ISO format (optional)',
+        },
+        endDate: {
+          type: 'string',
+          description: 'End date in ISO format (optional)',
+        },
+        timezone: {
+          type: 'string',
+          description: 'Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.',
+        },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+// Handle list tools request
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'get_conversation_history': {
+        const history = await historyService.getConversationHistory({
+          sessionId: args?.sessionId as string,
+          startDate: args?.startDate as string,
+          endDate: args?.endDate as string,
+          limit: (args?.limit as number) || 20,
+          offset: (args?.offset as number) || 0,
+          messageTypes: args?.messageTypes as ('user' | 'assistant' | 'system' | 'result')[],
+          timezone: args?.timezone as string,
+        });
+        return createResponse(history);
+      }
+
+      case 'search_conversations': {
+        const query = args?.query as string;
+        if (!query) {
+          throw new Error('Search query is required');
+        }
+
+        const results = await historyService.searchConversations(
+          query,
+          {
+            limit: (args?.limit as number) || 30,
+            projectPath: args?.projectPath as string,
+            startDate: args?.startDate as string,
+            endDate: args?.endDate as string,
+            timezone: args?.timezone as string,
+          }
+        );
+        return createResponse(results);
+      }
+
+      case 'list_projects': {
+        const projects = await historyService.listProjects();
+        return createResponse(projects);
+      }
+
+      case 'list_sessions': {
+        const sessions = await historyService.listSessions({
+          projectPath: args?.projectPath as string,
+          startDate: args?.startDate as string,
+          endDate: args?.endDate as string,
+          timezone: args?.timezone as string,
+        });
+        return createResponse(sessions);
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: ${errorMessage}`,
+      }],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Claude Code History MCP Server started');
+}
+
+main().catch((error) => {
+  console.error('Failed to start server:', error);
+  process.exit(1);
+});

package/example/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ebowwa/claudecodehistory",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "TypeScript library for accessing and analyzing Claude Code conversation history",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist/",
+    "example/",
     "README.md",
     "LICENSE"
   ],