@iflow-mcp/georgejeffers-uk-case-law-mcp 1.0.0

package/src/formatters.ts

@@ -0,0 +1,226 @@
+// src/formatters.ts
+// ============================================================================
+// OUTPUT FORMATTERS
+// ============================================================================
+//
+// Format search results and case content for Claude.
+// Designed to be readable and include proper citations.
+// ============================================================================
+
+import type { SearchResult, CaseContent, CaseParagraph } from './types.js';
+
+// ============================================================================
+// PARAGRAPH RANGE UTILITIES
+// ============================================================================
+
+export function parseParaRange(range: string): { start: number; end: number } | null {
+  const match = range.match(/^(\d+)\s*-\s*(\d+)$/);
+  if (!match || !match[1] || !match[2]) return null;
+  return {
+    start: parseInt(match[1], 10),
+    end: parseInt(match[2], 10),
+  };
+}
+
+// Maximum characters to return (roughly 8000 tokens)
+const MAX_OUTPUT_CHARS = 32000;
+
+export function applyParaRange(
+  paragraphs: CaseParagraph[],
+  range: string | undefined
+): { paragraphs: CaseParagraph[]; truncated: boolean; remaining: number } {
+  if (!range) {
+    // No range specified - apply token limit
+    return truncateToLimit(paragraphs);
+  }
+
+  const parsed = parseParaRange(range);
+  if (!parsed) {
+    return truncateToLimit(paragraphs);
+  }
+
+  const filtered = paragraphs.filter(
+    p => p.number >= parsed.start && p.number <= parsed.end
+  );
+
+  return truncateToLimit(filtered);
+}
+
+function truncateToLimit(paragraphs: CaseParagraph[]): {
+  paragraphs: CaseParagraph[];
+  truncated: boolean;
+  remaining: number;
+} {
+  let totalChars = 0;
+  const output: CaseParagraph[] = [];
+
+  for (const para of paragraphs) {
+    if (totalChars + para.text.length > MAX_OUTPUT_CHARS) {
+      break;
+    }
+    output.push(para);
+    totalChars += para.text.length;
+  }
+
+  return {
+    paragraphs: output,
+    truncated: output.length < paragraphs.length,
+    remaining: paragraphs.length - output.length,
+  };
+}
+
+// ============================================================================
+// SEARCH RESULTS FORMATTER
+// ============================================================================
+
+export function formatSearchResults(results: SearchResult[]): string {
+  if (results.length === 0) {
+    return 'No cases found matching your search query.';
+  }
+
+  let output = `Found ${results.length} case${results.length === 1 ? '' : 's'}:\n\n`;
+
+  for (const result of results) {
+    // Citation or URI as header
+    const citation = result.neutralCitation || result.documentUri;
+    output += `**${citation}**\n`;
+
+    // Title
+    output += `${result.title}\n`;
+
+    // Court and date
+    const parts: string[] = [];
+    if (result.court) parts.push(result.court);
+    if (result.date) parts.push(result.date);
+    if (parts.length > 0) {
+      output += `${parts.join(' | ')}\n`;
+    }
+
+    // Snippet if available
+    if (result.snippet) {
+      const cleanSnippet = result.snippet
+        .replace(/\s+/g, ' ')
+        .trim()
+        .substring(0, 200);
+      output += `> ${cleanSnippet}${cleanSnippet.length >= 200 ? '...' : ''}\n`;
+    }
+
+    // Add document links
+    output += `[View on TNA](${result.urls.web}) | [PDF](${result.urls.pdf})\n`;
+
+    output += '\n';
+  }
+
+  return output.trim();
+}
+
+// ============================================================================
+// CASE CONTENT FORMATTER
+// ============================================================================
+
+export interface FormatOptions {
+  includeMetadata?: boolean;
+  paragraphRange?: string;
+}
+
+export function formatCaseContent(
+  caseData: CaseContent,
+  options: FormatOptions = {}
+): string {
+  const { includeMetadata = true, paragraphRange } = options;
+
+  let output = '';
+
+  // Metadata header
+  if (includeMetadata) {
+    output += `# ${caseData.metadata.title}\n\n`;
+
+    if (caseData.metadata.neutralCitation) {
+      output += `**Citation:** ${caseData.metadata.neutralCitation}\n`;
+    }
+
+    output += `**Court:** ${caseData.metadata.courtName || caseData.metadata.court}\n`;
+
+    if (caseData.metadata.date) {
+      output += `**Date:** ${caseData.metadata.date}\n`;
+    }
+
+    if (caseData.judges && caseData.judges.length > 0) {
+      output += `**Judges:** ${caseData.judges.join(', ')}\n`;
+    }
+
+    if (caseData.parties) {
+      if (caseData.parties.claimants.length > 0) {
+        output += `**Claimant(s):** ${caseData.parties.claimants.join(', ')}\n`;
+      }
+      if (caseData.parties.defendants.length > 0) {
+        output += `**Defendant(s):** ${caseData.parties.defendants.join(', ')}\n`;
+      }
+    }
+
+    // Add document links
+    output += `\n[View on TNA](${caseData.metadata.urls.web}) | [PDF](${caseData.metadata.urls.pdf})\n`;
+
+    output += '\n---\n\n';
+  }
+
+  // Apply paragraph range and truncation
+  const { paragraphs, truncated, remaining } = applyParaRange(
+    caseData.paragraphs,
+    paragraphRange
+  );
+
+  // Format paragraphs with numbers for citation
+  for (const para of paragraphs) {
+    output += `[${para.number}] ${para.text}\n\n`;
+  }
+
+  // Truncation notice
+  if (truncated) {
+    output += `---\n\n`;
+    output += `*Output truncated. ${remaining} paragraph${remaining === 1 ? '' : 's'} remaining. `;
+    const lastPara = paragraphs[paragraphs.length - 1];
+    if (lastPara) {
+      output += `Use the paragraphs parameter (e.g., "${lastPara.number + 1}-${lastPara.number + 50}") to retrieve more.*\n`;
+    }
+  }
+
+  return output.trim();
+}
+
+// ============================================================================
+// CITATIONS FORMATTER
+// ============================================================================
+
+export function formatCitations(
+  citations: { citing: any[]; cited: any[] },
+  direction: 'citing' | 'cited' | 'both'
+): string {
+  let output = '';
+
+  if (direction === 'citing' || direction === 'both') {
+    output += `## Cases Citing This Decision\n\n`;
+    if (citations.citing.length === 0) {
+      output += `No citing cases found.\n\n`;
+    } else {
+      for (const c of citations.citing) {
+        output += `- **${c.citation || c.title}** (${c.court}, ${c.date})\n`;
+      }
+      output += '\n';
+    }
+  }
+
+  if (direction === 'cited' || direction === 'both') {
+    output += `## Cases Cited By This Decision\n\n`;
+    if (citations.cited.length === 0) {
+      output += `No cited cases found.\n\n`;
+    } else {
+      for (const c of citations.cited) {
+        output += `- **${c.citation || c.title}** (${c.court}, ${c.date})\n`;
+      }
+      output += '\n';
+    }
+  }
+
+  return output.trim();
+}

package/src/search.ts

@@ -0,0 +1,108 @@
+// src/search.ts
+// ============================================================================
+// UNIFIED SEARCH LAYER
+// ============================================================================
+//
+// Combines results from:
+// 1. TNA API (2003+)
+// 2. Local PostgreSQL (pre-2003 BAILII content) - optional, when database configured
+//
+// Results are merged using Reciprocal Rank Fusion (RRF).
+// ============================================================================
+
+import { searchTna, COURT_CODE_MAP, LEGAL_AREA_COURTS } from './tna-client.js';
+import type { SearchResult } from './types.js';
+
+export interface SearchParams {
+  query: string;
+  legalArea?: string;
+  court?: string;
+  yearFrom?: number;
+  yearTo?: number;
+  limit?: number;
+  page?: number;
+}
+
+export async function searchCaseLaw(params: SearchParams): Promise<SearchResult[]> {
+  const limit = params.limit || 10;
+
+  // Determine which TNA courts to search
+  let tnaCourts: string[] | undefined;
+
+  if (params.court && params.court !== 'any') {
+    tnaCourts = COURT_CODE_MAP[params.court];
+  }
+
+  if (params.legalArea && params.legalArea !== 'any') {
+    const areaCourts = LEGAL_AREA_COURTS[params.legalArea];
+    if (areaCourts) {
+      // Intersect with court filter if both specified
+      if (tnaCourts) {
+        tnaCourts = tnaCourts.filter(c => areaCourts.includes(c));
+      } else {
+        tnaCourts = areaCourts;
+      }
+    }
+  }
+
+  // For MVP, only use TNA API
+  // TODO: Add local database search when PostgreSQL is configured
+  const tnaResults = await searchTna({
+    query: params.query,
+    courts: tnaCourts,
+    yearFrom: params.yearFrom,
+    yearTo: params.yearTo,
+    limit: limit,
+    page: params.page,
+  });
+
+  return tnaResults.slice(0, limit);
+}
+
+// ============================================================================
+// RECIPROCAL RANK FUSION (for future use with multiple sources)
+// ============================================================================
+//
+// Combines ranked lists from different sources.
+// Each document gets a score based on its rank in each list:
+//   score = sum(1 / (k + rank)) for each list
+//
+// k=60 is a standard constant that prevents top results from
+// dominating too heavily.
+// ============================================================================
+
+export function reciprocalRankFusion(
+  resultLists: SearchResult[][],
+  limit: number,
+  k: number = 60
+): SearchResult[] {
+  const scores = new Map<string, number>();
+  const docMap = new Map<string, SearchResult>();
+
+  for (const results of resultLists) {
+    for (let rank = 0; rank < results.length; rank++) {
+      const result = results[rank];
+      if (!result) continue;
+
+      const docId = result.documentUri || result.neutralCitation || result.title;
+
+      const currentScore = scores.get(docId) || 0;
+      scores.set(docId, currentScore + 1 / (k + rank + 1));
+
+      // Keep the first occurrence (usually has more complete metadata)
+      if (!docMap.has(docId)) {
+        docMap.set(docId, result);
+      }
+    }
+  }
+
+  // Sort by RRF score
+  const sortedIds = [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([id]) => id);
+
+  return sortedIds
+    .slice(0, limit)
+    .map(id => docMap.get(id))
+    .filter((r): r is SearchResult => r !== undefined);
+}

package/src/server.ts

@@ -0,0 +1,227 @@
+// src/server.ts
+// ============================================================================
+// UK CASE LAW MCP SERVER
+// ============================================================================
+//
+// Provides Claude with tools to search and retrieve UK case law.
+//
+// Tools provided:
+// - uklaw_search: Search across all case law
+// - uklaw_get_case: Get full text of a specific case
+// ============================================================================
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { searchCaseLaw } from './search.js';
+import { getCaseByUri, getCaseByCitation } from './cases.js';
+import { formatSearchResults, formatCaseContent } from './formatters.js';
+import type { SearchParams } from './search.js';
+
+// ============================================================================
+// SERVER INITIALIZATION
+// ============================================================================
+
+const server = new McpServer({
+  name: 'uk-case-law',
+  version: '1.0.0',
+});
+
+// ============================================================================
+// TOOL: uklaw_search
+// ============================================================================
+//
+// Primary search tool. Searches TNA API (2003+).
+// ============================================================================
+
+server.tool(
+  'uklaw_search',
+  `Search UK case law across all courts and tribunals.
+
+Returns ranked results with:
+- Neutral citations (e.g., [2024] UKSC 1)
+- Case titles
+- Courts and dates
+- Brief snippets
+
+Use filters to narrow results by court, legal area, or date range.
+
+Examples:
+- "patent obviousness test" - finds patent validity cases
+- "unfair dismissal procedure" - finds employment cases
+- "breach of fiduciary duty director" - finds company law cases`,
+
+  {
+    query: z.string()
+      .min(2)
+      .describe('Search terms - legal concepts, party names, or keywords'),
+
+    legal_area: z.enum([
+      'any',
+      'intellectual_property',
+      'commercial',
+      'company',
+      'employment',
+      'property',
+      'family',
+      'criminal',
+      'public_law',
+      'immigration',
+      'personal_injury'
+    ])
+      .default('any')
+      .describe('Filter by area of law'),
+
+    court: z.enum([
+      'any',
+      'supreme_court',
+      'court_of_appeal',
+      'high_court',
+      'crown_court',
+      'tribunals'
+    ])
+      .default('any')
+      .describe('Filter by court level'),
+
+    year_from: z.number()
+      .int()
+      .min(1800)
+      .max(2025)
+      .optional()
+      .describe('Earliest decision year'),
+
+    year_to: z.number()
+      .int()
+      .min(1800)
+      .max(2025)
+      .optional()
+      .describe('Latest decision year'),
+
+    limit: z.number()
+      .int()
+      .min(1)
+      .max(50)
+      .default(10)
+      .describe('Maximum results to return'),
+
+    page: z.number()
+      .int()
+      .min(1)
+      .default(1)
+      .describe('Page number for pagination. If results seem truncated or date range is not met, try next page.'),
+  },
+
+  async ({ query, legal_area, court, year_from, year_to, limit, page }) => {
+    try {
+      const params: SearchParams = {
+        query,
+        legalArea: legal_area === 'any' ? undefined : legal_area,
+        court: court === 'any' ? undefined : court,
+        yearFrom: year_from,
+        yearTo: year_to,
+        limit,
+        page,
+      };
+
+      const results = await searchCaseLaw(params);
+      const formatted = formatSearchResults(results);
+
+      return {
+        content: [{ type: 'text', text: formatted }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
+        }],
+        isError: true
+      };
+    }
+  }
+);
+
+// ============================================================================
+// TOOL: uklaw_get_case
+// ============================================================================
+//
+// Retrieves full text of a specific case. For TNA cases, fetches from API.
+//
+// Output includes numbered paragraphs for precise citation.
+// ============================================================================
+
+server.tool(
+  'uklaw_get_case',
+  `Retrieve the full text of a specific UK case.
+
+Accepts either:
+- Neutral citation: "[2007] EWCA Civ 588"
+- Document URI: "ewca/civ/2007/588"
+
+Returns the judgment with numbered paragraphs. Use paragraph numbers
+when citing specific passages, e.g., "as stated at [23]".
+
+For long judgments, use the paragraphs parameter to request a specific
+range (e.g., "1-50" for the first 50 paragraphs).`,
+
+  {
+    citation: z.string()
+      .describe('Neutral citation (e.g., "[2024] UKSC 1") or document URI (e.g., "uksc/2024/1")'),
+
+    paragraphs: z.string()
+      .optional()
+      .describe('Paragraph range to retrieve, e.g., "1-50" or "23-45". Omit for full text.'),
+
+    include_metadata: z.boolean()
+      .default(true)
+      .describe('Include case metadata (judges, date, court)')
+  },
+
+  async ({ citation, paragraphs, include_metadata }) => {
+    try {
+      // Determine if this is a neutral citation or URI
+      const isNeutralCitation = citation.startsWith('[');
+
+      const caseData = isNeutralCitation
+        ? await getCaseByCitation(citation)
+        : await getCaseByUri(citation);
+
+      if (!caseData) {
+        return {
+          content: [{ type: 'text', text: `Case not found: ${citation}` }],
+          isError: true
+        };
+      }
+
+      const formatted = formatCaseContent(caseData, {
+        includeMetadata: include_metadata,
+        paragraphRange: paragraphs,
+      });
+
+      return {
+        content: [{ type: 'text', text: formatted }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Failed to retrieve case: ${error instanceof Error ? error.message : 'Unknown error'}`
+        }],
+        isError: true
+      };
+    }
+  }
+);
+
+// ============================================================================
+// START SERVER
+// ============================================================================
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('UK Case Law MCP server running');
+}
+
+main().catch(console.error);