{"_id":"@beshkenadze/courtlistener-sdk","name":"@beshkenadze/courtlistener-sdk","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@beshkenadze/courtlistener-sdk","version":"1.1.0","description":"TypeScript SDK and MCP server for CourtListener API","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","type":"module","scripts":{"dev":"bun run src/index.ts","build":"bun run build.ts","generate":"orval","format":"biome format --write .","lint":"biome lint --write .","check":"biome check --write .","check:ci":"biome ci .","prepublishOnly":"bun run build","test":"bun test src","test:watch":"bun test --watch src","test:integration":"SKIP_INTEGRATION_TESTS=false bun test src","test:all":"bun test","mcp:server":"bun run src/mcp/server.ts","download":"echo 'No download script defined, use `bun run generate` to generate the SDK from the API specification.'"},"dependencies":{"@modelcontextprotocol/sdk":"^1.16.0","axios":"^1.10.0","zod":"^3.24.1"},"devDependencies":{"@biomejs/biome":"^2.1.2","@types/bun":"latest","@types/node":"^24.1.0","@us-legal-tools/tsconfig":"workspace:*","orval":"^7.10.0","typescript":"^5.8.3"},"peerDependencies":{"typescript":"^5.0.0"},"keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"homepage":"https://github.com/beshkenadze/ecfr-sdk#readme","repository":{"type":"git","url":"git+https://github.com/beshkenadze/ecfr-sdk.git","directory":"packages/courtlistener-sdk"},"bugs":{"url":"https://github.com/beshkenadze/ecfr-sdk/issues"},"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"license":"MIT","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp/index.d.ts","import":"./dist/mcp/index.mjs","require":"./dist/mcp/index.js"}},"_id":"@beshkenadze/courtlistener-sdk@1.1.0","gitHead":"382204b5f11991e9baf2fe4eb85d9aebb6b3a9c4","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-7ZFfMaZowTa4Hub+ECQk+/Q5uayKrwIbQlV6vDN1Uh45SLOSnUu1Koe/IWj0TuWiJmjdH9DcKH/yW1YZ7QLdgg==","shasum":"b3858c9d3ec2de305c90398ad63784f21d576fbe","tarball":"https://registry.npmjs.org/@beshkenadze/courtlistener-sdk/-/courtlistener-sdk-1.1.0.tgz","fileCount":10,"unpackedSize":20692,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCxSGqgA3EA58z7VdUzxXjQJarUhonLuMPMBoE/EVrwyQIhAKD6CtB4xqEu6KvdDsjNbKOWF1p+4B+i25M5sBRGSokJ"}]},"_npmUser":{"name":"beshkenadze","email":"beshkenadze@gmail.com"},"directories":{},"maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/courtlistener-sdk_1.1.0_1753447877309_0.2738656247963731"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T12:51:17.241Z","1.1.0":"2025-07-25T12:51:17.489Z","modified":"2025-07-25T12:51:17.722Z"},"maintainers":[{"name":"beshkenadze","email":"beshkenadze@gmail.com"}],"description":"TypeScript SDK and MCP server for CourtListener API","homepage":"https://github.com/beshkenadze/ecfr-sdk#readme","keywords":["courtlistener","legal","api","sdk","mcp","typescript","case-law","judges","courts"],"repository":{"type":"git","url":"git+https://github.com/beshkenadze/ecfr-sdk.git","directory":"packages/courtlistener-sdk"},"author":{"name":"Aleksandr Beshkenadze","email":"beshkenadze@gmail.com"},"bugs":{"url":"https://github.com/beshkenadze/ecfr-sdk/issues"},"license":"MIT","readme":"# @beshkenadze/courtlistener-sdk\n\nTypeScript SDK and MCP (Model Context Protocol) server for the CourtListener API - the largest free legal database.\n\n[![npm version](https://badge.fury.io/js/@beshkenadze%2Fcourtlistener-sdk.svg)](https://badge.fury.io/js/@beshkenadze%2Fcourtlistener-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- ⚖️ **Case Law** - Access millions of legal opinions from federal and state courts\n- 👨‍⚖️ **Judge Data** - Comprehensive judge profiles and biographical information\n- 🎙️ **Oral Arguments** - Audio recordings with metadata\n- 📚 **Citation Tools** - Advanced citation lookup and normalization\n- 💼 **PACER Integration** - Federal court docket access\n- 🔔 **Real-time Alerts** - Track changes to cases and dockets\n- 🤖 **MCP Server** - AI-ready server for integration with Claude and other AI assistants\n- 🔍 **Advanced Search** - Powerful search with Elasticsearch backend\n\n## Installation\n\n```bash\n# npm\nnpm install @beshkenadze/courtlistener-sdk\n\n# yarn\nyarn add @beshkenadze/courtlistener-sdk\n\n# pnpm\npnpm add @beshkenadze/courtlistener-sdk\n\n# bun\nbun add @beshkenadze/courtlistener-sdk\n```\n\n## Authentication\n\nThe CourtListener API requires authentication for most endpoints. Get your API token from [CourtListener](https://www.courtlistener.com/help/api/rest/#authentication).\n\n```typescript\n// Set via environment variable\nprocess.env.COURTLISTENER_API_TOKEN = 'your-token';\n\n// Or configure the axios instance directly\nimport { axiosInstance } from '@beshkenadze/courtlistener-sdk';\naxiosInstance.defaults.headers.common['Authorization'] = 'Token your-token';\n```\n\n## Quick Start\n\n### Basic Search\n\n```typescript\nimport { getSearch } from '@beshkenadze/courtlistener-sdk';\n\n// Search for Supreme Court cases\nconst results = await getSearch({\n  type: 'o', // opinions\n  q: 'first amendment',\n  court: 'scotus',\n  order_by: 'score desc',\n  highlight: 'text'\n});\n\nconsole.log(`Found ${results.count} cases`);\nresults.results.forEach(result => {\n  console.log(`- ${result.caseName} (${result.dateFiled})`);\n  if (result.snippet) {\n    console.log(`  Snippet: ${result.snippet}`);\n  }\n});\n```\n\n### Citation Lookup\n\n```typescript\nimport { postCitationLookup } from '@beshkenadze/courtlistener-sdk';\n\n// Look up citations\nconst citations = await postCitationLookup({\n  text: 'I need the case at 410 U.S. 113 and also 5 F.3d 1234.',\n  html: false\n});\n\nconsole.log('Found citations:');\ncitations.citations.forEach(cite => {\n  console.log(`- ${cite.normalized_cite}: ${cite.case_name}`);\n  console.log(`  Court: ${cite.court}`);\n  console.log(`  URL: ${cite.absolute_url}`);\n});\n```\n\n### Judge Information\n\n```typescript\nimport { getPeople, getPositions } from '@beshkenadze/courtlistener-sdk';\n\n// Search for judges\nconst judges = await getPeople({\n  name_last: 'Roberts',\n  court: 'scotus'\n});\n\n// Get judge positions\nfor (const judge of judges.results) {\n  const positions = await getPositions({\n    person: judge.id\n  });\n  \n  positions.results.forEach(pos => {\n    console.log(`${judge.name_full}: ${pos.position_type} at ${pos.court_name}`);\n  });\n}\n```\n\n### Docket Monitoring\n\n```typescript\nimport { getDockets, postDocketAlerts } from '@beshkenadze/courtlistener-sdk';\n\n// Search for dockets\nconst dockets = await getDockets({\n  q: 'Google',\n  court: 'cafc',\n  order_by: 'date_created desc'\n});\n\n// Create alert for a docket\nif (dockets.results.length > 0) {\n  const alert = await postDocketAlerts({\n    docket: dockets.results[0].id,\n    alert_type: 'subscription'\n  });\n  \n  console.log('Alert created:', alert.id);\n}\n```\n\n## API Reference\n\n### Search Endpoints\n\n- `getSearch` - Universal search across all content types\n- `getOpinions` - Search legal opinions\n- `getDockets` - Search dockets\n- `getAudio` - Search oral arguments\n\n### Case Law Endpoints\n\n- `getClusters` - Get opinion clusters\n- `getOpinions` - Get individual opinions\n- `getCitations` - Get citation objects\n\n### People & Courts\n\n- `getPeople` - Search judges and parties\n- `getPositions` - Get judge positions\n- `getCourts` - Get court information\n- `getPoliticalAffiliations` - Get political data\n\n### Financial Disclosures\n\n- `getFinancialDisclosures` - Judge financial disclosures\n- `getInvestments` - Investment records\n- `getPositions` - Position holdings\n- `getGifts` - Gift disclosures\n\n### PACER & RECAP\n\n- `getRecap` - RECAP document archive\n- `postRecapFetch` - Request PACER documents\n\n### Alerts & Monitoring\n\n- `getAlerts` - Manage search alerts\n- `getDocketAlerts` - Manage docket alerts\n\n## MCP Server\n\nThe MCP server allows AI assistants to interact with the CourtListener API.\n\n### Running the Server\n\n```bash\n# With authentication token\nCOURTLISTENER_API_TOKEN=your-token npx @beshkenadze/courtlistener-sdk/mcp\n\n# Or if installed locally\ncd node_modules/@beshkenadze/courtlistener-sdk\nCOURTLISTENER_API_TOKEN=your-token npm run mcp:server\n```\n\n### Integration with Claude\n\nAdd to your Claude configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"courtlistener\": {\n      \"command\": \"npx\",\n      \"args\": [\"@beshkenadze/courtlistener-sdk/mcp\"],\n      \"env\": {\n        \"COURTLISTENER_API_TOKEN\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n## Search Types\n\nWhen using the universal search endpoint, specify the type:\n\n- `o` - Opinions\n- `r` - RECAP documents\n- `d` - Dockets\n- `p` - People (judges)\n- `oa` - Oral arguments\n\n## Advanced Search Syntax\n\nCourtListener supports advanced search operators:\n\n```typescript\n// Proximity search\nq: '\"patent infringement\"~10'  // Within 10 words\n\n// Field-specific search\nq: 'caseName:\"Apple v. Samsung\"'\n\n// Boolean operators\nq: 'copyright AND (fair use OR transformative)'\n\n// Date ranges\nq: 'dateFiled:[2020-01-01 TO 2024-12-31]'\n```\n\n## Rate Limiting\n\nCourtListener has rate limits based on your account type:\n- Free tier: 5,000 requests/day\n- Membership tiers: Higher limits available\n\nThe SDK includes automatic retry logic for rate-limited requests.\n\n## Error Handling\n\n```typescript\nimport { getSearch } from '@beshkenadze/courtlistener-sdk';\n\ntry {\n  const results = await getSearch({\n    type: 'o',\n    q: 'search term'\n  });\n} catch (error) {\n  if (error.response?.status === 401) {\n    console.error('Invalid API token');\n  } else if (error.response?.status === 429) {\n    console.error('Rate limit exceeded');\n  } else {\n    console.error('API error:', error.message);\n  }\n}\n```\n\n## License\n\nMIT License - see [LICENSE](../../LICENSE) for details\n\n## Links\n\n- [GitHub Repository](https://github.com/beshkenadze/ecfr-sdk)\n- [npm Package](https://www.npmjs.com/package/@beshkenadze/courtlistener-sdk)\n- [CourtListener Website](https://www.courtlistener.com/)\n- [CourtListener API Documentation](https://www.courtlistener.com/help/api/rest/)\n- [Free Law Project](https://free.law/)","readmeFilename":"README.md","_rev":"1-fa23ae823af63bec02bc48b8598d77a8"}