MCP Insights Proxy v2

Context-efficient MCP server that executes OpenSearch queries and returns synthesized output instead of raw JSON.

Philosophy

Full query flexibility, synthesized output only.

You retain 100% of OpenSearch DSL capabilities. The proxy only transforms the output.

┌──────────────────────────────────────────────────────────────────────────┐
│  BEFORE (direct OpenSearch MCP)                                          │
│  Query → OpenSearch → 500+ lines raw JSON → Context window 💥            │
├──────────────────────────────────────────────────────────────────────────┤
│  AFTER (this proxy)                                                      │
│  Query → Proxy → OpenSearch → Proxy formats → 20-50 lines → Context ✅   │
└──────────────────────────────────────────────────────────────────────────┘

Key Difference from v1

| v1 (Limited) | v2 (Full Flexibility) | |--------------|----------------------| | 5-6 predefined tools | 1 main tool accepting ANY DSL | | Hardcoded query patterns | You build the query | | Limited aggregations | ALL aggregations supported | | No nested/has_parent | Full query DSL support |

Quick Start

1. Install

cd mcp-insights-proxy
npm install
npm run build

2. Configure MCP Client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "insights-proxy": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-insights-proxy/dist/index.js"],
      "env": {
        "OPENSEARCH_URL": "https://your-cluster:9200",
        "OPENSEARCH_INDEX": "channel_posts",
        "OPENSEARCH_USER": "username",
        "OPENSEARCH_PASS": "password"
      }
    }
  }
}

3. Restart Claude

Tools

`opensearch_query` (Main Tool)

Execute any OpenSearch DSL query. Full flexibility.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | query | object | Required. Full OpenSearch DSL query object | | index | string | Index name (default: channel_posts) | | output_format | enum | auto, table, list, summary, compact_json | | max_display | number | Max hits to show (default: 20, max: 50) |

Example - Complex aggregation with nested sub-aggs:

{
  "query": {
    "size": 0,
    "query": {
      "bool": {
        "must": [
          {"term": {"join_field": "post"}},
          {"term": {"channel.type": "ig"}}
        ],
        "filter": [
          {"range": {"published_at": {"gte": "now-30d"}}}
        ]
      }
    },
    "aggs": {
      "by_hashtag": {
        "terms": {"field": "hashtags", "size": 10},
        "aggs": {
          "avg_engagement": {"avg": {"field": "engagement"}},
          "top_creators": {"terms": {"field": "channel.name", "size": 3}}
        }
      }
    }
  }
}

Example - has_parent query:

{
  "query": {
    "query": {
      "bool": {
        "must": [
          {"term": {"join_field": "post"}},
          {
            "has_parent": {
              "parent_type": "channel",
              "query": {
                "bool": {
                  "must": [
                    {"term": {"channel.geo.country.code": "IT"}},
                    {"range": {"channel.followers": {"gte": 100000}}}
                  ]
                }
              }
            }
          }
        ]
      }
    },
    "sort": [{"engagement": "desc"}],
    "size": 10,
    "_source": ["channel.name", "engagement", "published_at"]
  }
}

`opensearch_count`

Quick count without full query overhead.

{
  "query": {
    "bool": {
      "must": [
        {"term": {"join_field": "post"}},
        {"term": {"hashtags": "skincare"}}
      ]
    }
  }
}

`opensearch_mapping`

Get field list for an index.

Output Formats

`auto` (default)

Automatically detects:

Aggregation-only → summary format
Few hits (≤5) → list format
Many hits → table format

`table`

| # | name | type | engagement | likes | published_at |
|---|------|------|------------|-------|--------------|
| 1 | creator1 | IG | 156K | 142K | 2025-01-15 |
| 2 | creator2 | TT | 98K | 89K | 2025-01-18 |

`list`

**1.** @creator1 (IG) • eng: 156K • likes: 142K • views: 2.3M • 2025-01-15
**2.** @creator2 (TT) • eng: 98K • likes: 89K • views: 1.8M • 2025-01-18

`summary`

Just counts and aggregation results, no individual hits.

`compact_json`

Minimal JSON with only _source (no _id, _score, _index metadata).

Aggregation Output Examples

Terms aggregation

**by_platform:**
  • ig: 45.2K
  • tt: 32.1K
  • yt: 12.8K

Stats aggregation

**engagement_stats:** count=89.1K avg=2.3K min=0 max=1.2M sum=205M

Nested sub-aggregations

**by_hashtag:**
  • **skincare** (12.4K)
    **avg_engagement:** 3.2K
    **top_creators:**
      • creator1: 342
      • creator2: 287
  • **beauty** (8.7K)
    **avg_engagement:** 2.8K
    ...

Context Savings

| Query Type | Raw JSON | Proxy Output | Savings | |------------|----------|--------------|---------| | Top 10 posts | ~3000 tokens | ~300 tokens | 90% | | Aggregation (5 buckets) | ~1500 tokens | ~150 tokens | 90% | | Complex nested agg | ~5000 tokens | ~400 tokens | 92% |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENSEARCH_URL | Yes | http://localhost:9200 | Cluster URL | | OPENSEARCH_INDEX | No | channel_posts | Default index | | OPENSEARCH_USER | No | - | Basic auth username | | OPENSEARCH_PASS | No | - | Basic auth password |

Development

npm run dev    # Development with auto-reload
npm run build  # Build for production
npm start      # Run production build

Architecture

┌─────────────┐     ┌────────────────────────────────────────────┐     ┌────────────┐
│             │     │           MCP Insights Proxy               │     │            │
│   Claude    │────▶│  1. Receive DSL query (any complexity)     │────▶│ OpenSearch │
│   (builds   │     │  2. Execute against cluster                │     │            │
│    full     │◀────│  3. Parse response                         │◀────│            │
│    DSL)     │     │  4. Format: table/list/summary             │     │            │
│             │     │  5. Return compact markdown                │     │            │
└─────────────┘     └────────────────────────────────────────────┘     └────────────┘
        │                           │
        │                    Returns:
        │                    "*45.2K hits • took 23ms*
        │                     
        │                     ## Aggregations
        │                     **by_platform:**
        │                       • ig: 45.2K
        │                       • tt: 32.1K
        │                     
        │                     ## Results
        │                     | # | name | engagement |..."
        │
        └─── ~300 tokens instead of ~3000

License

MIT

MCP Insights Proxy