Insights Proxy

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