Starting: Json Genius

[MarkSpectarium]

json_genius Phase 4: Analytics & MCP Server

Context

json_genius is a CLI tool for token-efficient JSON intelligence. Phases 1-3 are complete:

• Phase 1: Core infrastructure (streaming JSON parser, schema extraction)
• Phase 2: Sampling & queries (path-based queries, aggregations)
• Phase 3: Relationships & types (cross-file detection, MCP type resolution, joins)

Phase 4 Deliverables

1. Pre-built Analytics Reports (analyze command)

Create json_genius/src/analytics/reports.ts:

Purpose: Generate pre-built KPI reports that mirror the functionality of C:\Users\Aracos\Desktop\JsonScraper\analyze.py.

CLI:

npx json-genius analyze <directory> --report <report-name>

# Examples:
npx json-genius analyze ../data/LiveTest --report player-kpis
npx json-genius analyze ../data/LiveTest --report retention
npx json-genius analyze ../data/LiveTest --report progression
npx json-genius analyze ../data/LiveTest --report schema-summary

Built-in Reports:

1. player-kpis - Basic player statistics

   • Total players (from live.json)
   • Total characters (from chars.json)
   • Characters per player (min/max/avg)
   • Character class distribution

2. retention - Player retention metrics

   • D1/D3/D7 retention rates (based on deviceHistory timestamps)
   • New vs returning players
   • Churn analysis

3. progression - Character progression stats

   • Level distribution
   • Max level characters count
   • Equipment/gear statistics (if available)

4. schema-summary - Quick overview of all JSON files in directory

   • File sizes
   • Entity counts
   • Top-level structure summary

Implementation Notes:

• Use existing streaming infrastructure
• Reports should work on the data/LiveTest/ files (live.json + chars.json)
• Output in human-readable format with optional --format json for programmatic use

2. MCP Server

Create json_genius/src/mcp/server.ts and json_genius/src/mcp/tools.ts:

Purpose: Expose json_genius functionality as MCP tools for AI agents.

Server Setup (similar to code_knowledge):

# Add to CLI
npx json-genius serve [--data-dir <dir>]

MCP Tools to Expose:

Tool	Description	Parameters
get_schema	Get compact schema for a JSON file	file, depth?, format?
sample_data	Get sample entities	file, count?, path?, entityType?
query_json	Run path-based queries	file, select?, filter?, limit?
count_entities	Count entities with optional filter	file, filter?
group_by	Group and count by field	file, path, filter?
get_stats	Numeric field statistics	file, path, filter?
find_relationships	Discover cross-file links	file1, file2
resolve_type	Look up $type in codebase KB	typeName, project
join_files	Cross-file query	file1, file2, select?, filter?, leftKey?, rightKey?
run_report	Run pre-built analytics report	directory, report

Implementation Pattern (from code_knowledge):

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({
  name: 'json-genius',
  version: '0.1.0',
});

server.tool('get_schema', 'Get compact schema for a JSON file', {
  file: { type: 'string', description: 'Path to JSON file' },
  depth: { type: 'number', description: 'Max depth', optional: true },
}, async ({ file, depth }) => {
  // Call existing extractSchema function
});

const transport = new StdioServerTransport();
await server.connect(transport);

3. Claude Code Integration

Add MCP server registration instructions to the README or CLAUDE.md:

# Windows
claude mcp add json-genius -s project -- cmd /c "cd json_genius && npx json-genius serve"

# macOS/Linux  
claude mcp add json-genius -s project -- sh -c "cd json_genius && npx json-genius serve"

File Structure After Phase 4

json_genius/src/
├── analytics/
│   └── reports.ts              # NEW
├── mcp/
│   ├── server.ts               # NEW
│   └── tools.ts                # NEW
├── analyzer/
│   ├── relationship-finder.ts
│   ├── sampler.ts
│   └── schema-extractor.ts
├── type-resolver/
│   └── mcp-bridge.ts
├── query/
│   ├── aggregate.ts
│   ├── join.ts
│   └── path-query.ts
├── streaming/
│   └── json-stream.ts
├── cli.ts                      # Add analyze + serve commands
└── utils/
    └── logger.ts

Success Criteria

1. analyze --report player-kpis produces meaningful stats from LiveTest data
2. serve command starts MCP server that responds to tool calls
3. All 10 MCP tools work correctly
4. Type checking passes: pnpm typecheck
5. Build succeeds: pnpm build

Testing

cd json_genius

# Test analytics
npx json-genius analyze ../data/LiveTest --report player-kpis
npx json-genius analyze ../data/LiveTest --report schema-summary

# Test MCP server (manual - start server and send JSON-RPC)
npx json-genius serve
# Then in another terminal, send tool calls via stdin

Reference

Look at code_knowledge/src/mcp/ for MCP server implementation patterns:

• code_knowledge/src/mcp/server.ts - Server setup
• code_knowledge/src/mcp/tools.ts - Tool definitions

[MarkSpectarium]

Original issue description:

In the data/LiveTest folder we have two very very large Jsons.
We also have a project in C:\Users\Aracos\Desktop\JsonScraper.

Here's the challenge:
We need to find a programmatic way to understand the structures of both of the JSONS and how they relate to each other.
So that we can then in a later step build KPI analytics tooling on top of them.

So your task is to get an understanding of the JSONS in a token efficient manner as they're too large for you to parse wholesale.
I.e. what kind of tools, scripts etc. should we build to get an AI the ability to work efficiently with Jsons like that.

Note: Those Jsons are from out myths project. The structures and codebase analytics are connected to that via your /mcp skill. So that may help you in figuring this out.

Don't spawn a swarm engineer for this yet. This is an exploratory task to come up with a plan for how we can work with this first.

[MarkSpectarium]

TD Review Note: Original prompt preserved in issue history. Minor corrections applied to stream-json code example (fixed imports and added missing stream-chain dependency).