{"id":30872397,"url":"https://github.com/kehvinbehvin/json-mcp-filter","last_synced_at":"2025-09-07T22:32:22.418Z","repository":{"id":307586073,"uuid":"1030023567","full_name":"kehvinbehvin/json-mcp-filter","owner":"kehvinbehvin","description":"JSON MCP server to filter only relevant data for your LLM","archived":false,"fork":false,"pushed_at":"2025-08-06T05:35:22.000Z","size":72,"stargazers_count":10,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-06T23:58:47.203Z","etag":null,"topics":["claude-mcp","data","data-extraction","data-filtering","json","json-analysis","json-filter","json-mcp-server","json-parser","json-schema-inference","json-to-typescript","json-utilities","large-files","mcp","mcp-server","query","type-generation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kehvinbehvin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T01:06:53.000Z","updated_at":"2025-08-26T02:35:15.000Z","dependencies_parsed_at":"2025-08-01T03:19:57.541Z","dependency_job_id":"39d332c5-1c7d-453f-89f4-29ab5e8221e9","html_url":"https://github.com/kehvinbehvin/json-mcp-filter","commit_stats":null,"previous_names":["kehvinbehvin/json-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kehvinbehvin/json-mcp-filter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehvinbehvin%2Fjson-mcp-filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehvinbehvin%2Fjson-mcp-filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehvinbehvin%2Fjson-mcp-filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehvinbehvin%2Fjson-mcp-filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kehvinbehvin","download_url":"https://codeload.github.com/kehvinbehvin/json-mcp-filter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehvinbehvin%2Fjson-mcp-filter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274046000,"owners_count":25212982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-mcp","data","data-extraction","data-filtering","json","json-analysis","json-filter","json-mcp-server","json-parser","json-schema-inference","json-to-typescript","json-utilities","large-files","mcp","mcp-server","query","type-generation"],"created_at":"2025-09-07T22:06:20.526Z","updated_at":"2025-09-07T22:32:22.397Z","avatar_url":"https://github.com/kehvinbehvin.png","language":"JavaScript","funding_links":[],"categories":["Search \u0026 Extraction","پیاده‌سازی‌های سرور","📦 Other"],"sub_categories":["Data APIs","🔎 \u003ca name=\"search\"\u003e\u003c/a\u003eجستجو و استخراج داده"],"readme":"# JSON MCP Filter\n\nA powerful Model Context Protocol (MCP) server that provides JSON schema generation and filtering tools for local files and remote HTTP/HTTPS endpoints. Built with [quicktype](https://github.com/quicktype/quicktype) for robust TypeScript type generation.\n\n\u003ca href=\"https://glama.ai/mcp/servers/@kehvinbehvin/json-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@kehvinbehvin/json-mcp/badge\" alt=\"JSON Server MCP server\" /\u003e\n\n**Perfect for**: Filtering large JSON files and API responses to extract only relevant data for LLM context, while maintaining type safety.\n\n\n## ✨ Key Features\n\n- 🔄 **Schema Generation** - Convert JSON to TypeScript interfaces using quicktype\n- 🎯 **Smart Filtering** - Extract specific fields with shape-based filtering  \n- 🌐 **Remote Support** - Works with HTTP/HTTPS URLs and API endpoints\n- 📦 **Auto Chunking** - Handles large datasets with automatic 400KB chunking\n- 🛡️ **Size Protection** - Built-in 50MB limit with memory safety\n- ⚡ **MCP Ready** - Seamless integration with Claude Desktop and Claude Code\n- 🚨 **Smart Errors** - Clear, actionable error messages with debugging info\n\n## 🛠️ Available Tools\n\n### `json_schema`\n\nGenerates TypeScript interfaces from JSON data.\n\n**Parameters:**\n- `filePath`: Local file path or HTTP/HTTPS URL\n\n**Example:**\n```javascript\n// Input JSON\n{\"name\": \"John\", \"age\": 30, \"city\": \"New York\"}\n\n// Generated TypeScript\nexport interface GeneratedType {\n    name: string;\n    age:  number;\n    city: string;\n}\n```\n\n### `json_filter`\n\nExtracts specific fields using shape-based filtering with automatic chunking for large datasets.\n\n**Parameters:**\n- `filePath`: Local file path or HTTP/HTTPS URL\n- `shape`: Object defining which fields to extract\n- `chunkIndex` (optional): Chunk index for large datasets (0-based)\n\n**Auto-Chunking:**\n- ≤400KB: Returns all data\n- \u003e400KB: Auto-chunks with metadata\n\n### `json_dry_run`\n\nAnalyzes data size and provides chunking recommendations before filtering.\n\n**Parameters:**\n- `filePath`: Local file path or HTTP/HTTPS URL  \n- `shape`: Object defining what to analyze\n\n**Returns:** Size breakdown and chunk recommendations\n\n## 📋 Usage Examples\n\n### Basic Filtering\n```javascript\n// Simple field extraction\njson_filter({\n  filePath: \"https://api.example.com/users\",\n  shape: {\"name\": true, \"email\": true}\n})\n```\n\n### Shape Patterns\n```javascript\n// Single field\n{\"name\": true}\n\n// Nested objects\n{\"user\": {\"name\": true, \"email\": true}}\n\n// Arrays (applies to each item)\n{\"users\": {\"name\": true, \"age\": true}}\n\n// Complex nested\n{\n  \"results\": {\n    \"profile\": {\"name\": true, \"location\": {\"city\": true}}\n  }\n}\n```\n\n### Large Dataset Workflow\n```javascript\n// 1. Check size first\njson_dry_run({filePath: \"./large.json\", shape: {\"users\": {\"id\": true}}})\n// → \"Recommended chunks: 6\"\n\n// 2. Get chunks\njson_filter({filePath: \"./large.json\", shape: {\"users\": {\"id\": true}}})\n// → Chunk 0 + metadata\n\njson_filter({filePath: \"./large.json\", shape: {\"users\": {\"id\": true}}, chunkIndex: 1})\n// → Chunk 1 + metadata\n```\n\n## 🔒 Security Notice\n\n**Remote Data Fetching**: This tool fetches data from HTTP/HTTPS URLs. Users are responsible for:\n\n✅ **Safe Practices:**\n- Verify URLs point to legitimate endpoints\n- Use trusted, public APIs only\n- Respect API rate limits and terms of service\n- Review data sources before processing\n\n❌ **Maintainers Not Responsible For:**\n- External URL content\n- Privacy implications of remote requests\n- Third-party API abuse or violations\n\n💡 **Recommendation**: Only use trusted, public data sources.\n\n## 🚀 Quick Start\n\n### Option 1: NPX (Recommended)\n```bash\n# No installation required\nnpx json-mcp-filter@latest\n```\n\n### Option 2: Global Install\n```bash\nnpm install -g json-mcp-filter@latest\njson-mcp-server\n```\n\n### Option 3: From Source\n```bash\ngit clone \u003crepository-url\u003e\ncd json-mcp-filter\nnpm install\nnpm run build\n```\n\n## ⚙️ MCP Integration\n\n### Claude Desktop\n\nAdd to your configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"json-mcp-filter\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"json-mcp-filter@latest\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\n# Add via CLI\nclaude mcp add json-mcp-filter npx -y json-mcp-filter@latest\n```\n\nOr add manually:\n- **Name**: `json-mcp-filter`\n- **Command**: `npx`\n- **Args**: `[\"-y\", \"json-mcp-filter@latest\"]`\n\n## 🔧 Development\n\n### Commands\n```bash\nnpm run build      # Compile TypeScript\nnpm run start      # Run compiled server  \nnpm run inspect    # Debug with MCP inspector\nnpx tsc --noEmit   # Type check only\n```\n\n### Testing\n```bash\nnpm run inspect    # Interactive testing interface\n```\n\n## 📁 Project Structure\n\n```\nsrc/\n├── index.ts                    # Main server + tools\n├── strategies/                 # Data ingestion strategies\n│   ├── JsonIngestionStrategy.ts  # Abstract interface\n│   ├── LocalFileStrategy.ts      # Local file access\n│   └── HttpJsonStrategy.ts       # HTTP/HTTPS fetching\n├── context/\n│   └── JsonIngestionContext.ts   # Strategy management\n└── types/\n    └── JsonIngestion.ts          # Type definitions\n```\n\n## 🚨 Error Handling\n\n### Comprehensive Coverage\n- **Local Files**: Not found, permissions, invalid JSON\n- **Remote URLs**: Network failures, auth errors (401/403), server errors (500+)\n- **Content Size**: Auto-reject \u003e50MB with clear messages\n- **Format Detection**: Smart detection of HTML/XML with guidance\n- **Rate Limiting**: 429 responses with retry instructions\n- **Processing**: Quicktype errors, shape filtering issues\n\n**All errors include actionable debugging information.**\n\n## ⚡ Performance\n\n### Processing Times\n| File Size | Processing Time |\n|-----------|-----------------|\n| \u003c 100 KB  | \u003c 10ms         |\n| 1-10 MB   | 100ms - 1s     |\n| 10-50 MB  | 1s - 5s        |\n| \u003e 50 MB   | **Blocked**    |\n\n### Size Protection\n- **50MB maximum** for all sources\n- **Pre-download checking** via Content-Length\n- **Memory safety** prevents OOM errors\n- **Clear error messages** with actual vs. limit sizes\n\n### Best Practices\n- Use `json_dry_run` first for large files\n- Filter with `json_filter` before schema generation\n- Focus shapes on essential fields only\n\n## 🌐 Supported Sources\n\n- **Public APIs** - REST endpoints with JSON responses\n- **Static Files** - JSON files on web servers\n- **Local Dev** - `http://localhost` during development\n- **Local Files** - File system access\n\n## 💡 Common Workflows\n\n**LLM Integration:**\n1. API returns large response\n2. `json_filter` extracts relevant fields\n3. Process clean data without noise\n4. `json_schema` generates types for safety","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkehvinbehvin%2Fjson-mcp-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkehvinbehvin%2Fjson-mcp-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkehvinbehvin%2Fjson-mcp-filter/lists"}