DEV Community: Nishikanta Ray

Smashing the "Blind Spot" Bug: How We Integrated Sentry to Catch Regressions in Real-Time

Nishikanta Ray — Sat, 08 Aug 2026 20:38:12 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

The Challenge: Flying Blind in Production

Pull Request - https://github.com/NishikantaRay/InsightTrack/commit/a70ca0a00c8cd169a93b300cfcb450b5ecbde7f8

Before this summer, our analytics platform, InsightTrack, had a fundamental flaw in how it handled observability. We were tracking standard JavaScript errors via a basic window.onerror handler, but it was just noise. We had no stack traces, no grouped fingerprints, and absolutely no release context.

If a customer integrated 10 different sites into our platform, we couldn't accurately tell them if a specific spike in errors was a brand-new issue or a resurrected bug from three deployments ago. We were flying blind, and our users were feeling the pain of delayed bug resolutions.

The ultimate "bug" wasn't a single line of broken code; it was our entire error observability pipeline.

The Solution: A Deep-Dive Sentry Integration

We decided to smash this architectural bug by building a native, robust integration with Sentry. We didn't just want to add a widget; we wanted to bring Sentry's rich context (fingerprinted grouping, permalinks, regression status, and user-impact counts) directly into the InsightTrack dashboard so traffic and bugs could be watched side-by-side.

How We Built It

To make this work seamlessly at scale (where one customer might poll 10 independent Sentry projects simultaneously), we built a dual-path ingestion system:

The Polling Backstop: We set up a bounded worker pool (to prevent slow projects from stalling the fleet) that polls the Sentry API every 5 minutes. To respect rate limits, we built an adaptive cadence—active projects poll frequently, while quiet or erroring projects exponentially back off.
The Near-Real-Time Webhook: For instant visibility, we allowed users to point a Sentry Internal Integration webhook at our API. Using HMAC signatures verified in constant time against a stored secret, new or regressed issues hit our database in milliseconds.

The Golden Rule of our Architecture:
All writes (polls and webhooks) go to PostgreSQL. A background sync then pushes this data to DuckDB every 60 seconds. All dashboard reads and analytics queries come only from DuckDB for lightning-fast performance.

The "Smash" Moment 🔨

We deployed the Sentry integration to production on a Tuesday. On Wednesday morning, it paid off spectacularly.

A customer pushed a massive UI update to their e-commerce site. Within three minutes, our newly built Error Spike Alerts—which calculate a 2-sigma (2σ) z-score against a 7-day rolling mean of Sentry events—fired off an alarm in their dashboard.

Because we were pulling in Sentry's substatus API field, the issue surfaced with a glaring red Regressed badge right in our UI.

Instead of opening five different tabs to figure out what went wrong, the customer clicked the row in our dashboard. This triggered our Live Drill-Down feature, which makes an on-demand, real-time fetch directly to Sentry's /events/latest/ endpoint. The stack trace, breadcrumbs, and tags populated instantly.

The bug? A deprecated checkout component that had been accidentally uncommented during a merge conflict. It was identified, patched, and deployed before most of their users even woke up.

What I'm Proud Of

I am incredibly proud of how resilient we made this system. By decoupling the write path (PostgreSQL) from the read path (DuckDB), the dashboard remains incredibly fast even if the polling workers are churning through thousands of Sentry pagination cursors in the background.

I'm also proud of the AI Analyst (Pulse) tools we built on top of this. Because the data is so cleanly structured in DuckDB, we exposed read-only MCP tools (get_error_summary and get_error_issues). Now, users can literally chat with their analytics dashboard and ask, "Did yesterday's deploy cause any regressions?" and the AI will read the synced Sentry data to give them a perfect answer.

What I Learned

Handling external APIs requires defensive programming. Assuming an API will always return what you expect is a recipe for disaster. Building in graceful degradation and adaptive backoffs (like dropping to a 6-hour poll cadence on a 401 Auth Fail) kept our system from DDOSing ourselves with bad tokens.
Webhooks + Polling = The perfect marriage. Webhooks are great for speed, but polling is necessary for accurate counts and state reconciliation (e.g., soft-deleting issues that have aged out). Using both gives you the best of both worlds.

Thanks to Sentry and the DEV community for the motivation to finally smash this architectural bug!

The ultimate "bug" wasn't a single line of broken code; it was our entire error observability pipeline.
Github - https://github.com/nishikantaray/InsightTrack
Website - https://insightstrack.dev
Pull Request - https://github.com/NishikantaRay/InsightTrack/commit/a70ca0a00c8cd169a93b300cfcb450b5ecbde7f8
Portfolio - https://nishikanta.in/

Building an AI-native Second Brain with Multi-RAG, Knowledge Graphs, and MCP

Nishikanta Ray — Sat, 08 Aug 2026 02:38:21 +0000

Claude is incredibly good at reasoning.

But reasoning is only as useful as the context available to it.

Your architecture might be in GitHub. Your notes might be in Obsidian. Your decisions might be buried in Slack. Your research might be in PDFs. Your project history might exist across hundreds of conversations.

The information exists.

The problem is that your AI doesn't have a unified way to understand it.

So I started thinking:

What if Claude had a persistent Second Brain?

Not another chatbot. Not another vector database.

A knowledge layer that Claude can query, learn from, and write back to.

What Is a Second Brain?

A Second Brain is a personal knowledge management system that helps you capture, organize, connect, and retrieve information outside your biological memory.

Tools like Obsidian made this idea powerful.

You can write simple Markdown notes and connect them:

InsightTrack
    │
    ├── [[DuckDB]]
    ├── [[PostgreSQL]]
    └── [[MCP]]

Obsidian then creates a visual graph of those relationships.

But there is a limitation:

Obsidian knows the relationships you explicitly create.

AI can take this much further.

Imagine having:

architecture.md
      │
      └── mentions DuckDB

GitHub PR #481
      │
      └── changes DuckDB queries

Slack discussion
      │
      └── explains why DuckDB was selected

benchmark.md
      │
      └── contains performance results

A human may never manually connect all four.

An AI-native knowledge system can discover those relationships automatically.

From Second Brain to AI Brain

A traditional Second Brain mainly answers:

"Where did I save this?"

An AI-native Second Brain should answer:

"What do we know about this, where did it come from, and how is it connected to everything else?"

That requires more than vector search.

It requires multiple retrieval strategies working together.

Why Traditional RAG Isn't Enough

A typical RAG architecture looks like:

Documents
    ↓
Chunking
    ↓
Embeddings
    ↓
Vector Search
    ↓
LLM

This works extremely well for semantic similarity.

Ask:

"What was the reasoning behind our analytics architecture?"

Vector search can find relevant discussions even if the exact wording is different.

But now ask:

"Where is SYNC_BATCH_SIZE defined?"

That's an exact identifier.

Keyword search is better.

Or ask:

"What services depend on PostgreSQL?"

That's a relationship question.

A knowledge graph is better.

This is why I think a serious AI Second Brain needs Multi-RAG.

Multi-RAG: Different Questions Need Different Retrieval

Instead of relying on one retrieval technique:

Semantic Search
       +
Full-Text Search
       +
Knowledge Graph
       +
Metadata Filtering
       +
Reranking

Each method solves a different problem.

Semantic RAG

Good for understanding concepts.

"Why did we choose DuckDB?"

Keyword RAG

Good for exact information.

"Find references to SYNC_BATCH_SIZE."

Graph RAG

Good for relationships.

"Which services depend on PostgreSQL?"

Memory Retrieval

Good for decisions and persistent context.

"What did we decide about the analytics architecture?"

Together, they provide much richer context than vector search alone.

The Architecture

The important idea isn't any individual component.

It's how the components work together.

Obsidian / Documents / External Sources
                │
                ▼
           Event Queue
                │
                ▼
        Processing Workers
          │      │      │
          ▼      ▼      ▼
       Metadata Embedding Graph
          │      │      │
          └──────┼──────┘
                 ▼
          Knowledge Layer
                 │
      ┌──────────┼──────────┐
      ▼          ▼          ▼
   Vector      Search      Graph
   Search      Index       Store
      │          │          │
      └──────────┼──────────┘
                 ▼
          Retrieval Engine
                 │
                 ▼
              MCP / API
                 │
                 ▼
          Claude / GPT / AI

Obsidian Is the Human Interface

I don't see Obsidian as the entire Second Brain.

I see it as one of the best human-facing knowledge interfaces.

You can continue writing naturally:

# Analytics Architecture

InsightTrack uses [[DuckDB]] for analytical queries.

Data originates in [[PostgreSQL]].

See [[Pulse]] for the AI analytics layer.

Obsidian gives you human-readable notes and a native graph.

The AI system adds another layer on top.

Two Graphs, Two Purposes

This architecture can maintain two different graphs.

Obsidian Graph

Created from explicit links:

[[InsightTrack]]
       │
       ▼
   [[DuckDB]]
       │
       ▼
  [[Analytics]]

This is primarily useful for human navigation.

System Entity Graph

Automatically extracted from all available knowledge:

InsightTrack
      │
     USES
      │
   DuckDB
   /    \
READS   SYNCED_FROM
 /          \

Pulse PostgreSQL

The system graph can be built from:

Markdown
Source code
Git commits
Pull requests
Database schemas
Documentation
Conversations
Meeting notes

This graph isn't just for visualization.

It becomes part of retrieval.

Knowledge Engineering + Graph Engineering

This is where the architecture becomes more interesting than a normal RAG application.

Knowledge Engineering turns raw information into structured knowledge.

Meeting Transcript
        ↓
     Summary
        ↓
   Action Items
        ↓
Architecture Decision
        ↓
   Project Memory

Graph Engineering connects the resulting entities.

Project
   ↓
Repository
   ↓
  API
   ↓
Database
   ↓
Developer
   ↓
Decision

The result isn't just a collection of documents.

It's a connected knowledge model.

The Retrieval Engine

The retrieval engine is arguably the most important part.

Suppose you ask:

Why did we move analytics queries from PostgreSQL to DuckDB?

The system might retrieve:

GitHub PR
      +
Architecture Note
      +
Benchmark
      +
Slack Discussion
      +
Decision Memory

Then rerank and combine the results.

Instead of giving Claude thousands of chunks, the system builds a focused context:

Decision:
Use DuckDB for analytical workloads.

Evidence:
- Benchmarks showed better aggregation performance.
- PostgreSQL remains the transactional source of truth.
- The architecture PR implemented the separation.
- The Slack discussion explains the operational trade-offs.

Now Claude is reasoning over evidence + relationships + memory.

Long-Term Memory

A Second Brain shouldn't remember everything.

Otherwise, it becomes another giant database.

It should remember what matters.

For example:

Decision
────────────────────
PostgreSQL remains the source of truth.

Decision
────────────────────
DuckDB handles analytical reads.

Reason
────────────────────
Better analytical performance and isolation.

Status
────────────────────
Implemented.

This is much more valuable than storing thousands of raw conversations.

The system should distinguish between:

Raw Data
   ↓
Information
   ↓
Knowledge
   ↓
Memory

That's an important part of making AI memory useful.

MCP Connects the Second Brain to Claude

This is where the architecture becomes AI-native.

Instead of building a custom integration directly into Claude, expose the Second Brain through MCP.

For example:

search()
retrieve()
remember()
ingest()
graph()
timeline()

Claude can ask:

search(
  "Why did we choose DuckDB?"
)

The Second Brain handles the complexity.

Claude doesn't need to know whether the answer came from:

PostgreSQL
pgvector
Search Index
Knowledge Graph
Obsidian
GitHub
Slack

It simply receives useful context.

Claude Can Write Back

This is where it becomes more than traditional RAG.

The flow isn't only:

Knowledge → AI

It becomes:

Knowledge ↔ AI

For example:

"Remember that we decided to keep PostgreSQL as the source of truth."

Claude calls:

remember(...)

The system can then:

Extract Entities
       ↓
Extract Relationships
       ↓
   Create Memory
       ↓
Generate Embedding
       ↓
   Update Graph
       ↓
   Store Source

The knowledge base becomes progressively richer.

The Model Doesn't Own the Knowledge

This is one of the most important ideas.

Today:

Claude
   ↓
Claude Memory

Another AI:

GPT
   ↓
GPT Memory

Another:

Gemini
   ↓
Gemini Memory

Everything is isolated.

Instead:

             Claude
                │
               GPT
                │
             Gemini
                │
              Cursor
                │
                ▼
         ┌───────────────┐
         │  Knowledge OS │
         └───────────────┘

The model can change.

The knowledge stays.

The Bigger Idea

I don't think the future is simply:

"Give Claude more context."

I think it's:

Build a persistent knowledge layer that every AI can use.

Obsidian can remain your human knowledge interface.

GitHub can remain your source-code system.

Slack can remain your communication system.

Your databases can remain your data systems.

Your AI assistants can remain your reasoning systems.

The Knowledge OS connects them.

Beyond the Second Brain

A traditional Second Brain helps you remember.

An AI-native Second Brain helps AI understand.

It combines:

Knowledge Engineering — turning raw information into structured knowledge
Graph Engineering — discovering entities and relationships
Hybrid Retrieval — combining semantic, keyword, and graph search
Long-Term Memory — preserving decisions and important context
MCP — making the knowledge available to AI agents and assistants

The result is something larger than a note-taking application or a vector database.

An AI-native Knowledge Operating System that combines Knowledge Engineering, Graph Engineering, Hybrid Retrieval, and Long-Term Memory into a unified platform accessible through MCP and APIs.

The LLM provides the reasoning.

The Knowledge OS provides the memory.

And MCP becomes the bridge between them.

Mind Maps in MCP: A Powerful Feature or Just Eye Candy?

Nishikanta Ray — Sat, 01 Aug 2026 18:27:45 +0000

Mind maps are an excellent addition to an MCP ecosystem when they help users understand relationships between data, tools, and reasoning. They should complement—not replace—traditional dashboards, tables, and chat interfaces.

Introduction

Large Language Models have become incredibly good at answering questions. Ask about your analytics, codebase, documentation, or infrastructure, and they'll generate a detailed response in seconds.

But there's a problem.

Most AI conversations are linear, while the problems we're solving are non-linear.

Imagine asking:

Why did traffic drop yesterday?

A traditional AI responds with several paragraphs of text.

A mind map, however, immediately shows the relationships between traffic sources, landing pages, countries, devices, deployments, and JavaScript errors.

Instead of reading hundreds of words, you understand the entire situation in seconds.

This naturally raises an interesting question:

Should every MCP server support mind maps?

After exploring different architectures and use cases, my conclusion is simple:

Yes—but only when they help users understand relationships rather than simply displaying information.

Let's explore why.

What is a Mind Map in MCP?

An MCP (Model Context Protocol) server exposes tools that AI models can use.

Normally the workflow looks like this:

User
  │
  ▼
LLM
  │
  ▼
MCP Tool
  │
  ▼
Database
  │
  ▼
Response

The AI collects data, summarizes it, and returns text.

Now imagine adding a visualization layer.

             User
               │
               ▼
          AI Planner
               │
      ┌────────┴────────┐
      ▼                 ▼
 Analytics Tool    Documentation Tool
      ▼                 ▼
 Error Tool        Code Search Tool
      ▼                 ▼
      └────────┬────────┘
               ▼
     Relationship Builder
               ▼
      Interactive Mind Map

The AI still performs the same work.

The difference is that users now see how everything connects instead of reading a long explanation.

Why Traditional AI Isn't Always Enough

Humans naturally think in relationships.

When someone asks:

Why are conversions down?

They aren't thinking linearly.

They're exploring multiple possibilities simultaneously.

Conversions
│
├── Traffic
│
├── Checkout
│
├── Marketing
│
├── Performance
│
├── Returning Users
│
└── Errors

Each branch creates another investigation.

This is exactly how troubleshooting works.

A mind map simply visualizes that thought process.

Real Analytics Example

Suppose an AI receives this question:

Why did yesterday's traffic decrease?

Instead of returning paragraphs, it could generate something like:

Traffic Drop
│
├── Organic Search ↓
│
├── Homepage ↓
│
├── India ↓
│
├── JavaScript Errors ↑
│
├── Core Web Vitals ↓
│
└── New Deployment ✓

Within seconds the user understands:

Organic search decreased
Homepage was affected
Most impact came from India
JavaScript errors increased
A deployment happened recently

The graph immediately tells a story.

Where Mind Maps Work Best

1. Analytics Investigation

Traditional dashboards answer:

How many visitors?
Which country?
Which browser?

Mind maps answer:

Why did traffic change?
Which metrics influence each other?
What caused this anomaly?

Example:

Traffic
│
├── Organic
│   ├── Landing Pages
│   ├── Keywords
│   └── Countries
│
├── Paid
│
├── Social
│
└── Referral

This transforms disconnected metrics into connected insights.

2. Documentation Search

Imagine asking:

Explain authentication.

Instead of returning dozens of documents, the AI groups concepts together.

Authentication
│
├── OAuth
├── JWT
├── API Keys
├── Sessions
└── Permissions

Users instantly understand the overall architecture.

3. Codebase Exploration

Large repositories can be overwhelming.

Instead of thousands of files:

Backend
│
├── API
│
├── Database
│   ├── PostgreSQL
│   └── Prisma
│
├── Authentication
│
└── Workers

Developers can navigate the repository visually.

4. AI Agent Planning

Most AI agents perform many hidden steps.

A mind map exposes them.

Task
│
├── Research
│
├── Search
│
├── Compare
│
├── Generate
│
└── Validate

This makes debugging AI workflows dramatically easier.

The Biggest Advantages

Better Understanding

Humans recognize patterns much faster than paragraphs.

Instead of reading 800 words, users understand the entire structure in seconds.

Relationship Discovery

Traditional dashboards display numbers.

Mind maps display relationships.

For example:

Deployment
      │
      ▼
JavaScript Errors
      │
      ▼
Checkout Failure
      │
      ▼
Revenue Drop

That chain is much harder to discover from charts alone.

Easier Navigation

Users don't need every detail immediately.

They can expand only the sections they care about.

Traffic
  │
  ├── Organic
  │
  ├── Direct
  │
  └── Social

This keeps complex systems manageable.

Better AI Transparency

Instead of wondering why the AI reached a conclusion, users can inspect the reasoning path visually.

This increases trust in AI-generated answers.

Where Mind Maps Fail

Like every visualization, they have limitations.

Everything Becomes a Graph

One common mistake is trying to visualize every piece of information.

Imagine this:

Visitors
│
├── Countries
├── Browsers
├── Devices
├── Sessions
├── Events
├── Campaigns
├── Pages
├── Heatmaps
├── Errors
├── Funnels
├── Scroll Depth
├── UTM
├── Performance
└── ...

After a few hundred nodes, the graph becomes unreadable.

Tables Are Sometimes Better

Suppose someone asks:

Show today's visitors.

They don't need a graph.

They need this:

Hour	Visitors
9 AM	241
10 AM	318
11 AM	401

Not every question benefits from visualization.

Performance

Large graphs become expensive.

Some challenges include:

Thousands of nodes
Complex edge calculations
Layout algorithms
Browser memory usage
Slow rendering

Most graph libraries begin struggling once graphs become extremely large unless clustering or virtualization is implemented.

Additional Maintenance

Relationships don't build themselves.

Every new feature means:

New node types
New edge rules
Updated layouts
Better ranking algorithms

Graph maintenance quickly becomes its own subsystem.

Common Mistakes

Many developers build graphs that simply mirror database tables.

Example:

Country
   │
   ▼
India
   │
   ▼
Users
   │
   ▼
5000

That provides almost no value.

Instead, focus on relationships.

Example:

Traffic Drop
│
├── Homepage
├── Organic Search
├── India
└── JavaScript Errors

The graph explains why something happened.

Should Every MCP Include Mind Maps?

Not necessarily.

Here's a simple rule.

Great Fit	Poor Fit
Documentation	Raw SQL
AI reasoning	CSV exports
Research	Tables
Architecture	Dashboards
Agent workflows	Metric reports
Knowledge graphs	Simple searches

Mind maps are strongest when users need to understand connections, not just retrieve information.

A Better Architecture

Rather than replacing the existing interface, add mind maps as an exploration mode.

Dashboard
│
├── Visitors
├── Revenue
├── Funnels
├── Heatmaps
└── Errors

        │
        ▼

🧠 Explore Relationships

        │
        ▼

Traffic
│
├── Acquisition
├── Geography
├── Pages
├── Errors
└── Performance

The dashboard remains familiar.

The graph becomes a discovery tool.

This hybrid approach gives users the best of both worlds.

Recommended Libraries

If you're planning to build interactive graph visualizations, these libraries are worth considering.

React Flow

Perfect for:

Interactive editors
Expandable nodes
Workflow builders
AI reasoning graphs

Cytoscape.js

Excellent for:

Large relationship graphs
Knowledge visualization
Network analysis

AntV G6

Great for:

Enterprise dashboards
Knowledge graphs
Automatic layouts

Sigma.js

Designed for:

Very large graphs
High-performance rendering
Thousands of nodes

D3.js

Ideal when you need complete customization and don't mind writing more code.

My Recommendation

If I were designing an MCP platform today, I wouldn't make the mind map the default interface.

Instead, I'd treat it as an optional exploration layer.

Users should still have access to:

Traditional chat
Tables
Dashboards
Charts
SQL results

When they want to understand relationships, they can switch to the graph view.

This keeps the interface simple while providing powerful visualization when it's genuinely useful.

Final Thoughts

Mind maps aren't valuable because they look impressive.

They're valuable because they help users understand relationships that are difficult to see in text, tables, or dashboards.

For MCP ecosystems, they're especially effective for:

AI reasoning
Documentation discovery
Codebase exploration
Knowledge graphs
Multi-agent workflows
Analytics investigations

However, they should never replace dashboards or structured data.

The most effective MCP platforms will combine both approaches:

Chat for conversations
Dashboards for metrics
Mind maps for relationships

Use each interface where it excels.

In the end, the goal isn't to make AI prettier—it's to make complex information easier to understand.

Running Hermes Agent with Kokoro TTS: A Local-First AI Assistant Setup

Nishikanta Ray — Sun, 26 Jul 2026 07:19:14 +0000

Most AI agents today depend heavily on cloud APIs. They're fast, but every request costs money, depends on an internet connection, and sends your data to external providers.

Over the weekend, I experimented with Hermes Agent and Kokoro TTS, building a completely local voice-enabled AI assistant. The result was surprisingly good—responses were generated locally, converted into natural speech, and even delivered through Telegram.

It felt much closer to having a personal AI operating system than simply chatting with an LLM.

What is Hermes Agent?

Hermes Agent is an open-source AI agent framework from Nous Research designed for long-running AI workflows. Unlike a traditional chatbot, Hermes can:

Execute tools
Remember previous interactions
Learn reusable skills
Schedule recurring jobs
Connect with messaging platforms like Telegram
Work with both cloud and local models

It also supports OpenAI-compatible endpoints, making it easy to swap between cloud providers and local inference engines.

Why use Kokoro TTS?

Kokoro is a lightweight text-to-speech engine that runs locally and produces surprisingly natural voices.

Instead of sending text to cloud TTS providers, everything happens on your own machine.

Benefits

Completely offline
No API costs
Low latency
Privacy-friendly
Easy integration with local AI workflows

For demos, assistants, and automation, it feels almost instant.

Architecture

                User
                  │
          Telegram / CLI
                  │
          ┌───────────────┐
          │ Hermes Agent  │
          └──────┬────────┘
                 │
      ┌──────────┴──────────┐
      │                     │
 Local LLM             Tool Calls
(Qwen/Llama/etc.)      Browser/MCP/etc.
      │
      ▼
 Response Text
      │
      ▼
 Kokoro TTS
      │
      ▼
 Natural Voice
      │
      ▼
 Telegram Voice Message

The same response can be delivered as:

Text
Voice
Or both simultaneously

Why run locally?

A local-first setup offers several advantages:

Privacy

Sensitive conversations never leave your machine unless you explicitly enable external tools.

Zero inference cost

After downloading the models, you no longer pay per request.

Faster iteration

Developers can test prompts, agents, and automations without worrying about API limits.

Offline capability

Useful for demos, labs, or environments with limited internet access.

Typical Setup

A common local stack looks like this:

Hermes Agent
Ollama or another OpenAI-compatible local model server
Kokoro TTS
Telegram Gateway (optional)
MCP servers
Local memory and skills

Hermes can connect to local model servers such as Ollama, LM Studio, vLLM, llama.cpp, and other OpenAI-compatible endpoints.

Real Use Cases

Personal AI Assistant

Ask questions and receive spoken replies.

Coding Agent

Read repositories, execute tools, and explain code aloud.

Customer Support Bot

Generate text and voice responses without cloud inference costs.

Home Automation

Control local services with voice feedback.

Content Creation

Generate narration for tutorials, demos, podcasts, and videos.

Research Assistant

Summarise documents and listen instead of reading long reports.

Pros

✅ Local inference

✅ Better privacy

✅ No recurring API costs

✅ Natural voice responses

✅ Works with existing OpenAI-compatible APIs

✅ Flexible model switching

✅ Extensible through tools and skills

Cons

❌ Requires decent CPU/GPU resources

❌ Initial model downloads can be large

❌ Local models may be slower than premium cloud models

❌ Voice quality depends on the selected TTS model

❌ Some external tools (web search, browser automation, cloud speech) still require internet access if enabled.

Who should use this?

This setup is ideal for:

AI developers
Open-source enthusiasts
Privacy-conscious users
Local LLM experimentation
Voice assistant projects
Internal enterprise tooling

If you're already using MCP servers or self-hosted AI infrastructure, Hermes integrates naturally into that workflow.

Final Thoughts

Hermes Agent combined with Kokoro TTS creates a surprisingly capable local AI assistant. Instead of just generating text, the system can reason, use tools, remember context, and respond with natural speech—all while keeping inference largely on your own machine.

For developers building AI assistants, coding agents, research tools, or voice-enabled applications, this local-first stack offers an excellent balance between privacy, flexibility, and cost.

After experimenting with it over the weekend, it's easy to see why local AI workflows are becoming increasingly practical. Cloud models still have their place for the hardest reasoning tasks, but for many day-to-day workflows, a local setup is already more than capable.

InsightsTrack + Pulse: I taught Claude Desktop to read my web analytics (via MCP)

Nishikanta Ray — Sun, 12 Jul 2026 15:01:53 +0000

This is a submission for Weekend Challenge: Passion Edition

What I Built

InsightsTrack is a self-hosted, privacy-first web analytics platform — the open-source alternative to Google Analytics. No cookies, no consent banner, no data selling. You run it on your own server and get real-time visitors, funnels, heatmaps, Core Web Vitals, and 17+ analytics views.

But the part I'm passionate about — and the reason I'm submitting it here — is Pulse: a built-in AI analyst that turns your analytics into a conversation.

Instead of hunting through dashboards, you just ask:

"What were my top pages last week?"
"Where is my traffic coming from?"
"Where are users dropping off in the funnel?"

Pulse answers in plain English, with real charts, tables, and CSV exports — every number backed by a live tool call, never hallucinated.

And here's the passion project twist: Pulse isn't locked inside the dashboard. The same analytics tools are exposed over MCP (Model Context Protocol), so I can open Claude Desktop, Cursor, or any MCP client and ask it about my website traffic — and it queries InsightsTrack directly.

My goal: make your own analytics as easy to query as sending a text message — and make that capability portable to every AI tool you already use.

Demo

🔗 Live app: https://insightstrack.dev
▶️ Video walkthrough: https://youtu.be/LGZw8temtPY

What to show in the demo:

Open the dashboard, click Ask Pulse, type "top pages last 7 days" → watch it stream an answer + render a table with a CSV button and an Open pages → deep link.
Switch the same result between table / bar / line / donut with one click.
Open Claude Desktop → ask "which sites do I have in InsightsTrack, and what's my top traffic source this month?" → it calls the MCP tools and answers with live data.

Code

GitHub: https://github.com/NishikantaRay/InsightTrack

NishikantaRay / InsightTrack

Self-hosted, privacy-first web analytics — the open-source alternative to Google Analytics

📊 InsightsTrack

Self-hosted, privacy-first web analytics — the open-source alternative to Google Analytics

Track visitors, pageviews, conversions, heatmaps, and Core Web Vitals — all on your own server. No cookies, no consent banners, no data selling. Deploy in under 15 minutes.

Live Demo · Quick Start · Features · Deploy · Docs

What is InsightsTrack?

InsightsTrack is a complete, production-grade web analytics platform you run yourself. It gives you the depth of Google Analytics 4 — real-time visitors, traffic sources, funnels, heatmaps, Web Vitals — without sending a single byte of your visitors' data to a third party.

Why teams choose it:

🔒 Privacy by design — no cookies, no fingerprinting, anonymous visitor IDs, GDPR-compliant, DNT/GPC honored.
⚡ Fast at any scale — a dual-database design (PostgreSQL for writes, DuckDB for reads) answers 90-day queries in under 100 ms even over millions of events.
🧩 Everything in one place —…

View on GitHub

The parts most relevant to this submission:

MCP tool registry — analytics-db/src/mcp/tools/registry.js (17 read-only tools)
MCP protocol handler (JSON-RPC 2.0, remote Streamable-HTTP transport) — analytics-db/src/mcp/protocol.js
The stdio bridge for local clients — mcp-server/src/index.js
The AI loop + BYO-key provider layer (Anthropic / OpenAI / Gemini) — analytics-db/src/routes/assistant.js and analytics-db/src/mcp/llm/provider.js

How I Built It

The dual-database core

InsightsTrack writes every tracking event to PostgreSQL and streams it into DuckDB, an embedded columnar engine. All analytics reads hit DuckDB — 90-day queries answer in tens of milliseconds, in-process, with no separate query cluster. Writes go to Postgres, reads come from DuckDB. That separation is what makes it fast and cheap to self-host.

Pulse: one tool registry, two front doors

The interesting decision was not building the AI assistant and the MCP integration as two separate things. There's one registry of 17 read-only tools (get_kpi, get_top_pages, get_funnel, get_realtime, list_sites, …). That single registry powers:

The in-dashboard Pulse panel — a streaming chat loop that lets an LLM call the tools and renders each result as a chart/table/KPI card.
MCP — the exact same tools, exposed to external clients.

Because both surfaces share the registry, an answer is consistent everywhere and I only maintain the tools once.

MCP: two transports

This is the connector heart of the project. I implemented both MCP transports:

Remote (Streamable-HTTP) — POST /api/mcp/http speaks JSON-RPC 2.0 (initialize / tools/list / tools/call). Clients that support remote MCP connect with just a URL + a bearer connect token. Nothing to install.
Local (stdio bridge) — a tiny mcp-server process (the only place the real @modelcontextprotocol/sdk is used) runs next to the client, speaks stdio, and proxies every call over HTTP to the API. It never touches the database — which keeps per-user site scoping and DuckDB's single-writer lock intact.

Connect tokens are scoped JWTs (scope: 'mcp', with jti so they can be revoked one-by-one), so a leaked token from one laptop can be killed without affecting others. All tools are read-only — the AI can query but can never change or delete data.

Bring-your-own-key, encrypted at rest

Pulse runs on your model key — Anthropic (Claude), OpenAI (GPT), or Google (Gemini). Keys are stored AES-256-GCM encrypted (dependency-free node:crypto, key derived from the server secret) and never leave your server. Precedence is BYO-key first, server key as fallback — so a self-hoster can either let every user bring their own, or set one server key so it "just works."

Result cards that do real work

Every tool returns a structured envelope — { summary, data, render, download, deepLink }. The dashboard turns that into a card with a CSV export, a view switcher (table ↔ bar ↔ line ↔ donut, client-side, no re-query), and a deep link to the matching dashboard page. Over MCP, the same envelope ships as structuredContent so agent clients get the data too.

The honest hard part

Getting Gemini to work over its OpenAI-compatible endpoint surfaced a subtle streaming bug: OpenAI streams tool-call arguments as fragments to concatenate, but Gemini sends the complete arguments object per delta (and sometimes repeats it) — naive concatenation produced invalid JSON like {}{} that Gemini then rejected on the next round. The fix: if an incoming fragment is already valid JSON, treat it as the whole value instead of appending. One provider quirk, but it's the difference between "Gemini works" and a mysterious INVALID_ARGUMENT.

Prize Categories

Best Use of Google AI — Pulse supports Google Gemini as a first-class model provider for the AI analyst. Bring a Gemini API key in Settings and every plain-English question about your analytics is answered by Gemini calling InsightsTrack's 17 read-only tools — in the dashboard and over MCP from Claude Desktop / Cursor.

Built with ❤️ as an open-source project. Try it, self-host it, or connect it to your favorite AI client. Feedback and stars welcome → https://github.com/NishikantaRay/InsightTrack

How I Finally Finished InsightTrack — My Abandoned Self-Hosted Analytics Platform

Nishikanta Ray — Sun, 24 May 2026 04:04:23 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

Project Details


Name	InsightTrack
GitHub	github.com/nishikantaray/insighttrack
Stack	React 18 · Vite 5 · Tailwind CSS · Express 4 · Node.js 20 · PostgreSQL · DuckDB

Demo

What I Built

InsightTrack is a self-hosted, privacy-first web analytics platform — my personal answer to the question "Why do I have to send all my users' data to Google just to know how many people visited my site?"

It tracks pageviews, sessions, conversions, user flows, and engagement — all on your own infrastructure, with no cookies and no third-party data sharing. The architecture uses PostgreSQL for all writes and DuckDB as an embedded columnar OLAP engine for analytics reads, achieving 10-100× the query speed of a traditional row-store setup.

I started InsightTrack during a long weekend when I was frustrated with the privacy implications of Google Analytics and the price tags on alternatives like Plausible and Fathom. The idea was simple: build a clean, self-hostable dashboard that you could drop a <script> tag into and be live in 5 minutes.

I got a working v1 out. It had a dashboard, auth, an onboarding wizard, basic charts, funnels, and a Docker Compose file that actually ran. Then I stopped. The project sat in a local folder for months — almost good enough, but not quite. The DuckDB sync was fragile. There was no dark mode on half the pages. Dozens of planned features were never built. Query performance fell apart past 30 days of data.

The bones were good. I just never gave it the finish it deserved.

How it works

Your Website
  └── analytics.js (tracking script, ~2 KB)
        │  POST /api/track/event
        ▼
  Express API (Node.js)
        │  Writes
        ▼
  PostgreSQL ──── Incremental sync worker (every 5 min)
                        │
                        ▼
                    DuckDB (OLAP reads)
                        │
                        ▼
  React Dashboard ◀─── GET /api/analytics/*

Write path: The tracking script sends events via navigator.sendBeacon. Express validates and inserts into PostgreSQL. Response is immediate — DuckDB is never in the write path.
Sync path: A high-watermark worker copies new rows from PostgreSQL → DuckDB incrementally, never rebuilding from scratch.
Read path: All 17 analytics endpoints read exclusively from DuckDB, running columnar aggregations 10-100× faster than a row-store query.
Auth: JWT-based authentication. All analytics routes are protected. Only /api/track/* and /api/auth/* are public.

PostgreSQL schema (source of truth)

Table	Purpose
`events`	Raw event log — pageviews, clicks, custom events
`sessions`	Session metadata — duration, page count, entry/exit pages
`sites`	Registered websites and their tracking keys
`funnels`	Funnel definitions with ordered steps
`daily_stats`	Pre-aggregated daily rollups
`users`	Dashboard user accounts

Demo

Landing Page

Hero

Features Grid

How It Works

Tech Stack

Comparison Table vs Google Analytics

Footer & CTA

Full landing page ![Full Landing Page](https://raw.githubusercontent.com/nishikantaray/insighttrack/main/screenshots/01-landing-full.png)

Authentication & Onboarding

Login	Register

Dashboard

Light Mode	Dark Mode

KPI Cards + Sparklines	Traffic Charts

Analytics Pages

User Flow (Sankey)	Real-Time

Funnels	Settings

Top Pages	Profile

Documentation	API Reference

Sidebar	Dark Landing

Stack: React 18 + Vite 5 + Tailwind CSS 3 · Express 4 + Node.js 20 · PostgreSQL + DuckDB · Docker Compose

The Comeback Story

Where it was (v1)

v1 had the core loop working: embed a tracking script → events land in PostgreSQL → a sync worker copies rows into a flat DuckDB table → the React dashboard reads from DuckDB. The fundamental architecture was sound.

What v1 shipped:

Dashboard with 4 KPI cards (Visitors, Pageviews, Bounce Rate, Avg. Session)
Traffic and pageview time-series charts (7d / 30d / 90d presets)
Top pages table
Basic conversion funnels
Device and country breakdown
JWT authentication, register/login, onboarding wizard with tracking snippet
Docker Compose deployment

But it had serious rough edges.

Performance wall. The DuckDB sync layer used a single flat table. On 90+ days of data, a KPI query scanned every row — ~620 ms on a local M1 machine. There was no partitioning, no archival strategy, and a crash meant rebuilding the entire table from scratch.

Half-finished features. There was a long list of planned but never-built ideas: UTM campaign tracking, comparison mode on charts, user flow analysis, a live visitor map on the Realtime page, engagement tracking, goal tracking, audience analytics, export to CSV/JSON — all unshipped.

UX gaps. The Settings page was a single form. The Documentation page was a placeholder. Half the pages lacked dark mode. There was no contextual help anywhere — a new user landing on the Funnels page had no idea what they were looking at.

No marketing story. The project had no landing page, no comparison table, no "why this instead of Google Analytics" pitch. It existed but didn't explain itself.

What changed (v1 → v2)

1. Hot+Cold Analytics Architecture

This was the most technically significant change. I replaced the flat DuckDB sync with a two-tier data lake:

Hot tier — DuckDB in-memory tables holding the last 30 days of events and sessions
Cold tier — Hive-partitioned Parquet files on disk for historical data, organized by site_id and event_date

data-lake/events/
  site_id=abc/
    event_date=2026-01-01/
      part-0001.parquet
    event_date=2026-01-02/
      part-0001.parquet

A transparent UNION ALL view sits on top of both tiers, so every existing dashboard query kept working without modification:

CREATE OR REPLACE VIEW events AS
  SELECT * FROM events_hot
  UNION ALL
  SELECT * FROM read_parquet(
    'data-lake/events/site_id=*/event_date=*/part-0001.parquet',
    hive_partitioning = true
  );

A dual-watermark incremental sync worker runs every 5 minutes, fetching only new rows from PostgreSQL using high-water marks (last_event_id for events, last_synced timestamp for sessions), then routing them to the correct tier based on age.

Result: 90-day queries dropped from ~620 ms → ~25 ms. A 25× speedup.

Recovery after a crash now resumes from the watermark instead of rebuilding the entire table.

2. Tracking Script — what it captures automatically

The auto-generated analytics.js (~2 KB) handles everything without configuration:

Data Point	How
Page URL & path	`window.location.href`
Referrer	`document.referrer`
Browser, OS, device	`navigator.userAgent` + screen width heuristics
Country	Timezone via `Intl.DateTimeFormat`
Session	Auto UUID in `sessionStorage`
Anonymous user ID	Random UUID in `localStorage` — no cookies
Outbound link clicks	`click` event listener
Scroll depth	25/50/75/100% milestones on page unload
Time on page	Seconds per page sent on unload
Heatmap clicks	x/y coordinates + CSS selector of every click
Rage clicks	3+ rapid clicks on same element within 1 second
Core Web Vitals	LCP, FID, CLS, INP, TTFB via `PerformanceObserver`
JS errors	`window.onerror` + `unhandledrejection` capture
Site search	Form submit interception
UTM parameters	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
SPA navigation	`popstate` + `pushState` / `replaceState` listeners

Privacy built-in: DNT (navigator.doNotTrack) and GPC (navigator.globalPrivacyControl) are respected — if either is set, no data is collected.

Custom events are available via window.analytics.track('event_name', { ...properties }).

3. Complete v2 feature set

Core Dashboard

The main dashboard now has comparison mode — every chart can overlay the current period against the previous period. All 4 KPI cards have sparkline mini-charts. Date picker supports custom ranges in addition to presets.

Real-Time

Active visitor count (users in last 5 minutes, with pulsing indicator)
Interactive world map pinpointing active visitors by country
Live event stream — feed of the last 50–100 events as they happen
Active pages ranked by current visitor count
Real-time device breakdown

Engagement Analytics

Four metrics measured automatically by the tracking script:

Metric	What it shows
Scroll Depth	Per-page average scroll %; milestone table (25/50/75/100%)
Click Heatmaps	x/y dot map per page, top clicked elements ranked
Rage Click Detection	Pages and elements triggering 3+ rapid clicks within 1 second
Time on Page	Average, median, min/max read time per page

User Flow & Funnels

Sankey diagram showing entry pages → transitions → exit pages with proportional path thickness
Multi-step funnel builder (e.g., Landing → Signup → Checkout → Purchase) with per-stage drop-off and conversion rate
Saved funnel definitions

Conversion & Goals

Goal types: Pageview (URL match), Event (custom event), Duration (time on page), Scroll Depth (threshold)
A/B test tracking — create experiments, assign variants, compare conversion rates
Revenue attribution — attach dollar values to purchase events, see total revenue and average order value by traffic source

Audience Analytics

New vs. returning visitors — pie/donut chart + daily trend
Cohort analysis — heatmap grid of Day 1 / Day 7 / Day 30 retention by first-visit week
Visitor segments — filter by device, browser, OS, country and compare KPIs side by side

Content Analytics

Entry pages — top landing pages ranked by visitor count and entry rate
Exit pages — top departure pages ranked by exit count and exit rate
Page flow — where visitors go after each page
Site search — queries captured from form submit interception with frequency counts

Acquisition Analytics

Full UTM campaign dashboard — source, medium, campaign, term, content breakdowns with visitor counts, bounce rates, and session duration
Social media tab — automatic classification of Facebook, Twitter/X, LinkedIn, Instagram, YouTube, Reddit, Pinterest, TikTok traffic
Search keyword tracking — organic and paid keywords driving traffic
UTM link builder — generate tagged URLs directly in the dashboard

Performance Monitoring

Core Web Vitals collected automatically:

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤ 2.5s	≤ 4.0s	> 4.0s
FID (First Input Delay)	≤ 100ms	≤ 300ms	> 300ms
CLS (Cumulative Layout Shift)	≤ 0.1	≤ 0.25	> 0.25
INP (Interaction to Next Paint)	≤ 200ms	≤ 500ms	> 500ms
TTFB (Time to First Byte)	≤ 800ms	≤ 1800ms	> 1800ms

Color-coded metric cards (green/yellow/red) + per-page breakdown table.

JavaScript error tracking: message, source file, line/column, stack trace, error trend chart over time.

Reporting & Export

Data export — JSON/CSV download for KPI, traffic, pages, sources data; PNG export for charts
Annotations — pin notes to specific dates on charts (e.g., "launched new homepage") with category badges (deployment/marketing/incident)
Scheduled reports — configure daily/weekly/monthly email delivery with recipient list
Custom dashboards — save personalized widget layouts

Multi-Site Management

Add and manage unlimited websites under one account
Per-site tracking snippets with one-click copy
Per-site data retention policies (30/90/180/365 days)
Automated cleanup of expired events and sessions

4. UX and documentation overhaul

Settings page rebuilt as a 4-tab layout: General, Notifications/Alerts, Site Manager, and Privacy
All 13 analytics pages gained a collapsible PageNote banner with a business explanation and a developer tip per page
InfoTooltip on every MetricCard and ChartCard
Documentation page rebuilt with dual-audience tabs (Business Owner / Developer) and an interactive 4-view architecture diagram
Dark mode enforced consistently across every page and component

5. Marketing landing page

Hero, features grid, 3-step "How It Works", tech stack cards, and a side-by-side comparison table vs. Google Analytics across 9 dimensions.

Before vs. After

Dimension	v1 (Before)	v2 (After)
90-day query time	~620 ms	~25 ms (25×)
DuckDB architecture	Single flat table, full scan	Hot (in-memory) + Cold (Parquet), UNION view
Sync on crash	Full table rebuild	Resumes from dual watermark
Analytics pages	7	13
Tracking data points	8	19
Real-Time page	Active count only	Map + event stream + device breakdown
Engagement tracking	None	Scroll depth, heatmaps, rage clicks, time on page
Conversion & Goals	Funnels only	Goals, A/B testing, revenue attribution
Audience analytics	None	New/returning, cohorts, segments
Content analytics	Top pages only	Entry/exit pages, page flow, site search
Acquisition analytics	None	UTM campaigns, social, keywords, link builder
Performance monitoring	None	Core Web Vitals + JS error tracking
Reporting	None	Export, annotations, scheduled reports, custom dashboards
Multi-site	Single site	Unlimited sites with per-site settings
Comparison mode	None	Previous-period overlay on all charts
Export	None	CSV / JSON / PNG
Settings page	Single form	4-tab layout with site manager
Contextual help	None	`PageNote` + `InfoTooltip` on every page
Dark mode coverage	Partial	Complete
Marketing landing page	None	Full page with comparison table

My Experience with GitHub Copilot

I'll be direct: I would not have shipped v2 without GitHub Copilot. Not because the individual problems were too hard — but because there were so many of them, and I was coming back to code I hadn't touched in months.

The architecture lift. The Hot+Cold DuckDB design required a new sync worker, new schema migrations, new UNION views, and updates to every existing query file simultaneously. Copilot helped me work through design decisions conversationally — I'd describe the constraint ("crash recovery must resume from a watermark, not rebuild the whole table") and it would walk me through the dual-watermark pattern, flag edge cases I hadn't considered (what happens to a row that ages from hot to cold between two sync cycles?), and generate the implementation that fit the existing codebase style.

The feature sweep. Going from 8 tracked data points to 19, from 7 pages to 13, from basic funnels to engagement tracking, cohort analysis, Web Vitals, and revenue attribution is a context-switching marathon. Copilot compressed the ramp-up time on each feature dramatically. When I opened the Acquisition page for the first time in months, Copilot immediately understood the existing data model, knew which UTM fields were already being captured in the tracking script, and scaffolded the campaign dashboard components that matched the existing useAnalytics hook pattern — not generic code, but code that fit this project.

The consistency work. The PageNote and InfoTooltip additions touched 13 pages. Adding Core Web Vitals collection to the tracking script required coordinating between analytics.js, the Express ingest route, the DuckDB schema, and the React performance page — four files that had to stay in sync. Copilot held the full context across all of them.

The documentation. Writing accurate technical docs for a system you know deeply is surprisingly tedious. Copilot drafted the architecture document for the hot/cold system from the actual code — referencing the real SQL, the real file paths, the real config variables — and I edited for clarity rather than writing from scratch.

The interaction style that worked best wasn't "write this for me." It was: here's the constraint, here's the existing pattern, here's where I'm confused. Copilot as a collaborator who has read your entire codebase is a genuinely different experience from Copilot as autocomplete. The finish-up phase of a project — juggling context across a dozen half-done things — is exactly where that kind of always-available, always-context-aware pair programmer pays off most.

InsightTrack v2 is the project I always meant to ship. It just needed time, a clear plan, and a better way to work through the backlog.

InsightTrack is open source — self-host your own privacy-first analytics in minutes.

SwiftCut: AI-Powered Video Silence Remover Built with GitHub Copilot CLI

Nishikanta Ray — Mon, 26 Jan 2026 16:46:06 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

SwiftCut is a local-first desktop application that automates the "Rough Cut" phase of video editing. It uses AI-powered audio analysis to instantly detect and remove silent segments from videos — no cloud uploads, no subscriptions, complete privacy.

The Problem I Solved

As a content creator, I spent hours manually cutting out silent pauses from my podcast recordings, tutorial videos, and vlogs. The workflow was:

Import video into heavy editing software
Scrub through timeline looking for silence
Manually mark and delete each silent segment
Repeat 50+ times per video 😩

SwiftCut automates this entire process in seconds.

Key Features

🎯 Smart Silence Detection — FFmpeg-powered audio analysis with configurable thresholds

⚡ Instant Results — Process a 10-minute video in under 5 seconds

🔒 100% Local & Private — Your videos never leave your machine

🎚️ Content Presets — Optimized settings for Podcasts, Tutorials, Vlogs, and Interviews

🤖 AI Natural Language Commands — Tell it what to do: "Remove all silences" or "Make a 30-second clip"

🎬 Reel Cutter — Split long videos into Instagram Reels, TikTok, or YouTube Shorts

🎙️ Voice Commands — Speak your edits using Web Speech API

↩️ Full Undo/Redo — Never lose your work

Tech Stack

Layer	Technology
Framework	Tauri v2 (Rust + WebView)
Frontend	React 19 + TypeScript
Styling	Tailwind CSS v4
State	Zustand
Video Processing	FFmpeg
AI	Multi-provider (Local, Ollama, OpenAI, Copilot SDK)

Demo

🎥 Video Walkthrough

▶️ Watch SwiftCut in Action

Screenshots

Landing Page — Clean, focused interface

Silence Detection — Visual timeline with detected segments

AI Commands — Natural language video editing

Reel Cutter — Split videos for social media

Try It Yourself

# Clone the repo
git clone https://github.com/yourusername/swiftcut.git
cd swiftcut

# Install dependencies
npm install

# Run in development
npm run tauri dev

# Build for production
npm run tauri:build

Requirements: Node.js 22+, Rust 1.93+, FFmpeg

My Experience with GitHub Copilot CLI

How Copilot CLI Transformed My Development

Building SwiftCut would have taken weeks without GitHub Copilot CLI. Here's how I used it:

1. FFmpeg Command Generation

FFmpeg has notoriously complex syntax. Instead of Googling for hours, I asked Copilot:

gh copilot suggest "ffmpeg command to detect silence below -30dB lasting more than 0.5 seconds"

Result:

ffmpeg -i input.mp4 -af "silencedetect=noise=-30dB:d=0.5" -f null -

This became the core of my silence detection algorithm.

2. Rust Backend Development

I'm primarily a TypeScript developer. Writing Rust for Tauri was daunting, but Copilot CLI helped:

gh copilot explain "how to parse FFmpeg stderr output in Rust and extract timestamps"

It gave me a complete regex pattern and parsing logic that I adapted for my lib.rs.

3. Complex Filter Chains

Building the export filter was tricky. I needed to keep non-silent segments and remove gaps:

gh copilot suggest "ffmpeg select filter to keep multiple time ranges and close gaps"

Result:

-vf "select='between(t,0,5)+between(t,8,20)',setpts=N/FRAME_RATE/TB"
-af "aselect='between(t,0,5)+between(t,8,20)',asetpts=N/SR/TB"

4. AI Planner System Prompt

I used Copilot to help design the system prompt for my AI planner:

gh copilot suggest "system prompt for an AI that converts natural language to FFmpeg commands"

This helped me structure the SWIFTCUT_SYSTEM_PROMPT that powers the natural language interface.

5. Cross-Platform Build Configuration

Setting up GitHub Actions for multi-platform builds:

gh copilot suggest "github actions workflow to build tauri app for mac windows and linux"

Got a working CI/CD pipeline in minutes instead of hours.

Impact on Development Experience

Metric	Without Copilot CLI	With Copilot CLI
FFmpeg learning curve	2-3 days	2 hours
Rust backend	1 week	2 days
Total development time	~3 weeks	~5 days
Stack Overflow visits	100+	~10

The "Aha!" Moment

The breakthrough came when I realized I could use Copilot CLI as a planning agent within the app itself. The system prompt I developed with Copilot's help now powers SwiftCut's AI command interface:

User: "Remove all silences longer than 1 second"
     ↓
AI Planner (Copilot-inspired prompt)
     ↓
FFmpeg: select='between(t,0,5)+between(t,8,20)...'
     ↓
Exported video with silences removed!

What I'd Tell Other Developers

Don't just ask for code — Ask Copilot CLI to explain concepts first
Use suggest for commands — Especially for complex CLI tools like FFmpeg, Docker, Git
Iterate with explain — If the first suggestion isn't perfect, ask it to explain and refine
Build your own prompts — The system prompts Copilot uses are great templates for your AI features

Technical Deep Dive

How Silence Detection Works

ORIGINAL VIDEO (10 minutes)
▓▓▓▓▓░░░▓▓▓▓▓▓▓░░▓▓▓▓░░░░▓▓▓▓▓▓▓▓░░▓▓▓▓▓▓░░░▓▓▓▓▓
     ▲       ▲       ▲           ▲         ▲
  silence silence silence    silence   silence

                    ↓ FFmpeg silencedetect

EXPORTED VIDEO (7 minutes)  
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
(All silence removed — 30% shorter!)

AI Provider Architecture

SwiftCut supports multiple AI backends:

type AIProvider = 'local' | 'copilot' | 'ollama' | 'openai';

// Switch providers in settings
setAIProvider({ 
  provider: 'ollama', 
  baseUrl: 'http://localhost:11434', 
  modelName: 'llama3.2' 
});

Provider	Use Case
Local	Offline, rule-based processing
Ollama	Privacy-focused local LLM
OpenAI	Most capable, requires API key
Copilot SDK	Coming soon!

What's Next

[ ] Waveform visualization in timeline
[ ] Transcript-based editing ("Find where I say 'demo'")
[ ] Batch processing multiple videos
[ ] Plugin system for custom filters
[ ] Mobile companion app

Acknowledgments

Built with ❤️ using:

Tauri — Amazing desktop framework
FFmpeg — The backbone of video processing
GitHub Copilot CLI — My AI pair programmer

What editing task takes you the longest? Let me know in the comments — maybe SwiftCut can help!

From Static to Smart: Designing an AI-First Developer Portfolio with Renderer, Gemini & MCP 🚀🚀

Nishikanta Ray — Thu, 22 Jan 2026 18:16:15 +0000

Transforming portfolio creation with Google Gemini AI and Model Context Protocol

https://www.youtube.com/watch?v=Txzplqg6oJo

🚀 Executive Summary

Renderer is an innovative portfolio framework that leverages Google Gemini to revolutionize how developers create and manage their online presence. By combining a configuration-first architecture with AI assistance through Model Context Protocol (MCP), users can generate, validate, and customize complete portfolios using natural language.

Key Innovation

Instead of wrestling with complex frameworks, users simply describe what they want, and Gemini handles the technical complexity—generating configurations, validating code, and providing instant guidance.

Live Links

🌐 Live Portfolio: https://nishikanta.in
📚 Documentation: https://renderer.nishikanta.in/docs
💻 Framework: https://github.com/NishikantaRay/renderer
🤖 MCP Server: https://github.com/NishikantaRay/renderer-mcp-server

🎯 Problem & Solution

The Problem

Developers face critical pain points when building portfolios:

⚠️ Framework Overload - Complex React/Vue setups with heavy build processes
⏰ Time Investment - Hours configuring, styling, and maintaining
🔒 Limited Flexibility - Templates that don't adapt to individual needs
📚 Documentation Fatigue - Searching through endless docs for simple changes

Our Solution

A static, configuration-driven framework enhanced by Google Gemini AI that:

✅ Generates complete portfolio configurations from natural language
✅ Validates TOML files and catches errors instantly
✅ Provides contextual documentation and examples
✅ Reduces setup time from hours to minutes

🧠 Google Gemini Integration

Dual-Layer AI Architecture

1. Gemini AI Studio (Ideation & Content Creation)

Used during initial development for:

📝 Outlining portfolio structure and sections
✍️ Drafting About, Resume, and project descriptions
🎨 Suggesting design patterns and layouts
🔄 Converting raw notes into polished copy

Why Gemini: Its advanced reasoning capabilities helped transform technical achievements into compelling narratives.

2. Gemini CLI (Development Workflow)

Terminal-native AI for rapid development:

# Generate configuration files
gemini "Create a resume.toml with experience and education sections"

# Content refinement
gemini "Rewrite this Markdown to be more technical and concise"

# Validation
gemini "Check this TOML file for schema errors"

# Documentation
gemini "Explain how to add dark mode to my portfolio"

Advantage: Seamlessly integrates with Git-based workflows and plain-text files.

3. Model Context Protocol (MCP) Server (AI Assistant)

Our breakthrough innovation—a persistent AI assistant that understands Renderer's architecture:

MCP Server Capabilities:

🔍 Semantic Documentation Search - Find answers in natural language
✅ Real-time TOML Validation - Catch errors before deployment
🎨 Template Generation - Create complete configs from user input
💡 Smart Examples - Context-aware code snippets
🗂️ Repository Navigation - Browse and understand file structure

🏗️ Technical Architecture

Core System

Renderer Framework
├── Configuration Layer (TOML)      # Human & AI readable
├── Content Layer (Markdown)        # Plain text documents
├── Presentation Layer (HTML/CSS/JS) # Vanilla web tech
└── AI Layer (Gemini + MCP)        # Intelligent assistance

Why This Stack Works

Configuration-Driven Design:

TOML files are both human and AI readable
No framework abstractions—pure data
Version control friendly
Deterministic output

Static-First Approach:

Zero build process
Instant deployment
Maximum performance
No server dependencies

AI-Assistable Architecture:

Every file is structured and parseable
Clear separation of concerns
Predictable patterns for AI reasoning

🤖 MCP Server Deep Dive

Architecture

Renderer MCP Server
├── GitHub Integration          # Access to framework repository
├── Documentation Engine        # Semantic search across docs
├── TOML Validator             # Schema validation
├── Template Generator         # Config creation
├── Example Provider           # Contextual snippets
└── Feature Search             # Capability discovery

Available Tools

explore_renderer_docs
- Natural language documentation queries
- Returns relevant sections with examples
validate_toml_config
- Schema validation
- Syntax checking
- Improvement suggestions
generate_starter_template
- Complete project scaffolding
- Customized to user needs
- Ready-to-deploy configurations
get_config_example
- Annotated configuration samples
- Context-aware suggestions
- Best practices included
search_renderer_features
- Feature discovery
- Implementation guides
- Integration examples

Setup & Usage

# Install globally
npm install -g renderer-mcp-server

# Use with Gemini CLI for AI assistance
gemini "Generate a portfolio configuration for John Doe with projects, resume, and blog"

# Or integrate with any MCP-compatible client
# The MCP server works with Google AI Studio API and Gemini models

💡 Real-World Use Cases

Use Case 1: Rapid Portfolio Generation

User: "I need a portfolio showcasing 5 projects, my resume, and a contact form"

Gemini + MCP Response:

Generates complete projects.toml with 5 project templates
Creates resume.toml with standard sections
Configures contact.html with form validation
Provides deployment instructions
Time saved: 2-3 hours → 10 minutes

Use Case 2: Configuration Validation

User: Uploads existing home.toml file

MCP Server:

✅ Validates syntax
⚠️ Identifies missing required fields
💡 Suggests improvements
📚 Links to relevant documentation

Use Case 3: Feature Discovery

User: "How do I add analytics dashboard to my projects page?"

Gemini Response:

[analytics]
enabled = true
title = "Project Analytics"

[analytics.charts]
weekly_activity = true
project_distribution = true

Plus step-by-step integration guide.

📊 Impact & Results

Quantifiable Improvements

Metric	Before	After	Improvement
Setup Time	4-6 hours	15-20 minutes	85% reduction
Configuration Errors	Common	Prevented	~90% reduction
Documentation Search	10-15 minutes	Instant	Near-instant
Portfolio Updates	30-45 minutes	5 minutes	83% faster

User Benefits

🚀 Developers: Focus on content, not configuration
🎨 Designers: Easy customization without code
📚 Students: Professional portfolios in minutes
💼 Professionals: Maintain portfolios effortlessly

🌟 Key Features

Portfolio Capabilities

🔧 Fully Configurable - Every aspect controlled via TOML
📄 Multi-Page Support - Home, Projects, Blog, Resume, Contact, Docs
🌙 Dark/Light Theme - Automatic detection + manual toggle
📱 Responsive Design - Mobile-first approach
⚡ Performance - Static files, instant loading
♿ Accessibility - Built-in ARIA support
🔍 SEO Optimized - Semantic HTML, proper meta tags

AI-Enhanced Workflows

💬 Natural Language Setup - Describe, don't configure
✅ Instant Validation - Real-time error checking
📝 Auto-Generation - Complete configs from prompts
🎯 Context-Aware Help - Relevant examples always
🔄 Iterative Refinement - Easy modifications

🎓 Technical Implementation

Configuration Example

# home.toml - Fully AI-generatable
[hero]
name = "Nishikanta Ray"
title = "Full-Stack Developer"
intro = [
    "Building developer-first tools and AI-assisted workflows",
    "Specialized in static-first architectures and minimal frameworks"
]

[hero.actions]
primary_text = "View Projects"
primary_link = "projects.html"
secondary_text = "Contact Me"
secondary_link = "contact.html"

[sections]
enabled_sections = ["projects", "skills", "experience"]

[theme]
mode = "auto"  # auto, light, or dark
accent_color = "#3b82f6"

MCP Tool Usage

// User prompt: "Create a blog config for tech writing"

// MCP generates:
{
  blog: {
    title: "Tech Blog",
    description: "Insights on web development",
    author: "Your Name"
  },
  settings: {
    posts_per_page: 6,
    enable_comments: true,
    enable_search: true,
    enable_categories: true
  },
  posts: [
    {
      id: "starter-post",
      title: "Welcome to My Blog",
      date: "2026-01-22",
      tags: ["introduction"]
    }
  ]
}

🚀 Getting Started

Option 1: AI-Assisted Setup (Recommended)

# 1. Install MCP Server
npm install -g renderer-mcp-server

# 2. Use Gemini CLI for AI assistance:
gemini "Create a portfolio configuration for [Your Name] with projects and resume"

# 3. Deploy to any static host
# Netlify, Vercel, GitHub Pages, Cloudflare Pages

Option 2: Manual Setup

# Clone repository
git clone https://github.com/NishikantaRay/renderer.git

# Serve locally
python -m http.server 8000
# or
npx serve .

# Configure via TOML files in config/
# Edit content in Markdown files

📚 Resources

Documentation

Repositories

Quick Start Commands

# Try the MCP server
npm install -g renderer-mcp-server

# Clone and run locally
git clone https://github.com/NishikantaRay/renderer.git
cd renderer && npx serve .

# Generate portfolio with Gemini CLI
gemini "Create a complete portfolio configuration for me"

👤 About the Creator

Nishikanta Ray - Full-Stack Developer specializing in:

🛠️ Developer experience and productivity tools
🤖 AI-assisted workflows and automation
🏗️ Minimal-framework, static-first architectures
📚 Open source contributions

Connect:

🌐 Portfolio: https://nishikanta.in
💻 GitHub: https://github.com/NishikantaRay

🎉 Conclusion

Renderer demonstrates the transformative potential of Google Gemini when applied to real-world developer workflows. By combining static-first architecture with intelligent AI assistance through MCP, we've created a system that:

This project proves that AI isn't just for chatbots—it's a fundamental tool for reimagining how we build and maintain software.

Built with Google Gemini | Powered by MCP | Made for Developers

Start building your AI-assisted portfolio today at renderer.nishikanta.in 🚀

Production-Grade Prompting with the Anthropic API

Nishikanta Ray — Sat, 17 Jan 2026 16:36:23 +0000

Concepts, Parameters, Streaming, Caching, and a Real Enterprise Example

Prompting in Anthropic (Claude) is not just about writing good instructions.

In production systems, prompts behave more like specifications than conversations.

This article explains how prompting actually works in Anthropic, how to design reliable and compliant prompts, and how to use JavaScript to build real systems—ending with a production-grade sentiment analysis prompt.

1. How Anthropic Prompting Really Works

Anthropic uses a message-based API.

Each request contains the entire conversation state.

Claude does not remember anything between API calls.

Mental model

You → send full conversation
Claude → continues from that context

Every request must include:

Who the assistant is
What rules apply
What the user just said
Any images or documents

2. Messages and Roles (Core Concept)

Anthropic uses three roles:

Role	Purpose
`system`	Hard rules, behavior, constraints
`user`	Input data or tasks
`assistant`	Previous model replies (conversation priming)

Example

messages: [
  { role: "user", content: "Hello! Only speak Spanish." },
  { role: "assistant", content: "Hola!" },
  { role: "user", content: "How are you?" }
]

Claude will answer in Spanish because:

Conversation history establishes the rule
Claude prioritizes consistency

Production rule

Put non-negotiable rules in system, not in conversation history.

3. System vs User Instructions (Why It Matters)

Instruction Type	Reliability
System	Strong, persistent
User	Soft, overrideable
Assistant	Priming only

Production-safe example

system: "You must respond only in Spanish."

This survives:

Long conversations
Truncated history
User attempts to override

4. Temperature: Controlling Randomness

Temperature controls how predictable Claude’s word choices are.

It does not control intelligence.

Temperature	Behavior	Use case
0.0–0.2	Deterministic	JSON, analytics
0.3–0.5	Controlled	Summaries
0.6–0.8	Creative	Writing
0.9+	Unstable	Rarely useful

Example

temperature: 0.0

Use this when:

Output must be parsed
Compliance matters
Decisions depend on correctness

5. stop_sequences: When the Model Must Stop

stop_sequences tells Claude when to stop generating.

stop_sequences: ["\nUser:"]

Claude stops immediately when it reaches that string.

Common uses

Prevent role leakage
End JSON cleanly
Stop agent loops

Key rule

Stop sequences are guards, not fixes for bad prompts.

6. Streaming Responses (Real-Time Output)

Streaming lets Claude send text incrementally.

with client.messages.stream(...) as stream:
  for text in stream.text_stream:
    print(text)

Why streaming exists

Faster perceived response
Better UX
Long outputs

When NOT to stream

JSON APIs
Tool calls
Strict schema validation

Production pattern

let buffer = "";

for (const chunk of stream.text_stream) {
  buffer += chunk;
  process.stdout.write(chunk);
}

// buffer now contains the full response

7. Multimodal Prompting (Images + Text)

Anthropic allows image + text together.

{
  role: "user",
  content: [
    { type: "image", source: {...} },
    { type: "text", text: "Count the containers." }
  ]
}

Rules

content must be an array
Image first, instruction second
Images only in user role

8. Prompt Caching and `cache_control`

Anthropic optimizes performance by caching repeated prompt prefixes.

This is good for:

System prompts
Templates
Policies

But dangerous for:

User data
Transcripts
Images
PII

9. `cache_control: { type: "ephemeral" }`

"cache_control": { "type": "ephemeral" }

This means:

Use this content once. Do not cache. Do not reuse. Do not persist.

When to use it

Data	Ephemeral
User input	✅
Call transcripts	✅
Images	✅
Customer feedback	✅

Why it matters

Prevents data reuse
Improves compliance posture
Reduces audit risk

10. JavaScript Example: Safe Prompt with Ephemeral Data

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 200,
  temperature: 0.0,
  system: "You are a deterministic analysis engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "The service was slow and frustrating.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

11. What Makes a Prompt Production-Grade

A production prompt has:

Clear role definition
Explicit constraints
Defined output format
Fail-closed behavior
Low temperature
No exposed reasoning
Safe handling of sensitive data

Good prompts are specifications, not conversations.

12. Production-Grade Sentiment Analysis Prompt

This prompt follows all best practices discussed above.

Prompt

Analyze the sentiment of the following customer message.

Rules:
- Classify sentiment as POSITIVE, NEGATIVE, or NEUTRAL
- Do not include personal data
- Do not infer intent beyond the text
- Limit text fields to 100 characters

Output:
Return ONLY valid JSON.
No explanations.

Schema:
{
  "sentiment": "POSITIVE | NEGATIVE | NEUTRAL",
  "confidence": 0.0-1.0,
  "summary": "string"
}

If sentiment cannot be determined, return:
{
  "sentiment": "NEUTRAL",
  "confidence": 0.0,
  "summary": "Insufficient data"
}

13. Sentiment Analysis: Full JavaScript Example

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 150,
  temperature: 0.0,
  system: "You are a strict sentiment classification engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Support was slow and unhelpful.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

14. Final Takeaway

Anthropic prompting works best when you treat prompts like contracts: explicit, constrained, deterministic, and safe.

Building an AI-Powered Portfolio Assistant with Model Context Protocol

Nishikanta Ray — Wed, 31 Dec 2025 08:27:46 +0000

How I Built a Smart Assistant for the Renderer Framework Using MCP

A comprehensive guide to creating your first MCP server with real-world examples

📖 Table of Contents

Introduction
What is Model Context Protocol?
The Problem We're Solving
Architecture Overview
Implementation Guide
Testing with Claude Desktop
Testing with MCP Inspector
Real-World Use Cases
Lessons Learned
What's Next

Introduction

Creating a portfolio website shouldn't be hard. But as the creator of Renderer, a TOML-driven portfolio framework, I noticed users struggling with:

Understanding TOML configuration syntax
Finding relevant documentation
Validating their configurations
Getting started quickly

The solution? An AI assistant that truly understands the framework. Not a generic chatbot, but a specialized tool that knows every configuration option, can validate your code, and guide you from zero to deployed.

Enter the Model Context Protocol (MCP) — a game-changing standard for connecting AI assistants with external tools and data sources.

In this post, I'll walk you through building Renderer MCP Server, a complete AI assistant that makes portfolio creation effortless. You'll learn:

How MCP works and why it's revolutionary
How to build your own MCP server from scratch
How to integrate it with Claude Desktop
Real-world testing and deployment strategies

GitHub Repository: renderer-mcp-server

Let's dive in! 🚀

What is Model Context Protocol?

The New Standard for AI Interoperability

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to securely access external tools, data sources, and services.

Think of it as "USB for AI" — just like USB standardized how devices connect to computers, MCP standardizes how AI connects to the world.

Why MCP Matters

Before MCP:

❌ Each AI tool had custom integration code
❌ Switching AI providers meant rebuilding everything
❌ No standard way to share tools across platforms
❌ Security and permissions were ad-hoc

After MCP:

✅ Write once, use with any MCP-compatible AI
✅ Standard protocol for tool communication
✅ Built-in security and permission model
✅ Growing ecosystem of shared tools

How MCP Works

┌─────────────────────────────────────────────────┐
│           AI Assistant (Claude, etc.)            │
│              "MCP Client"                        │
└────────────────────┬────────────────────────────┘
                     │ MCP Protocol
                     │ (JSON-RPC over stdio)
                     ▼
┌─────────────────────────────────────────────────┐
│              Your MCP Server                     │
│         (Custom Tools & Logic)                   │
└────────────────────┬────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
    GitHub API              File System
    Databases              External APIs
    Your Services          Anything!

Key Components:

MCP Client - The AI assistant (Claude Desktop, VS Code, etc.)
MCP Server - Your custom tool server
Tools - Individual capabilities you expose
Resources - Data sources the AI can access
Prompts - Reusable prompt templates

The Problem We're Solving

User Pain Points

When I launched Renderer, I saw users struggling with:

1. Steep Learning Curve

"How do I configure the home page?"
"What's the syntax for TOML arrays?"
"Where do I put my social media links?"

2. Documentation Discovery

"I know this feature exists, but where's the doc?"
"How do I search across all documentation?"
"What are all the available configuration options?"

3. Configuration Validation

"Why isn't my portfolio loading?"
"Is this TOML syntax correct?"
"What fields am I missing?"

4. Time-Consuming Setup

"It took me 2 hours just to get started"
"I had to read all the docs first"
"Too much trial and error"

The Vision

What if users could just ask for what they need?

User: "Create a portfolio for me with projects and resume"
AI: *Generates complete, valid configuration*

User: "Is my home.toml correct?"
AI: *Validates and suggests improvements*

User: "How do I add dark mode?"
AI: *Shows exact configuration with examples*

This is what Renderer MCP Server enables.

Architecture Overview

System Design

Our MCP server follows a clean, modular architecture:

renderer-mcp-server/
├── src/
│   ├── index.ts              # Main server & routing
│   ├── types.ts              # TypeScript definitions
│   ├── constants.ts          # Tool definitions
│   ├── github.ts             # GitHub API client
│   └── tools/                # Modular tool implementations
│       ├── validator.ts      # TOML validation
│       ├── template.ts       # Template generation
│       ├── examples.ts       # Config examples
│       ├── features.ts       # Feature search
│       └── guides.ts         # Setup guides
├── build/                    # Compiled JavaScript
└── package.json

Technology Stack

Core:

Runtime: Node.js 18+
Language: TypeScript 5.3+
Protocol: MCP via @modelcontextprotocol/sdk
Transport: stdio (standard input/output)

Integrations:

GitHub API: @octokit/rest for repository access
TOML Parser: toml for configuration validation
Markdown: marked for content processing

Why This Stack?

TypeScript - Type safety prevents runtime errors
Modular Design - Each tool is independent and testable
stdio Transport - Simple, universal, no networking
GitHub Integration - Direct access to documentation and examples

Implementation Guide

Let's build the MCP server step by step!

Step 1: Project Setup

# Create project structure
mkdir renderer-mcp-server
cd renderer-mcp-server
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk @octokit/rest toml marked

# Install dev dependencies
npm install -D typescript @types/node

# Initialize TypeScript
npx tsc --init

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Step 2: Define Types

src/types.ts:

/**
 * Type definitions for our MCP server
 */

export interface RendererConfig {
    owner?: string;
    repo?: string;
    branch?: string;
}

export interface TemplateOptions {
    name: string;
    email?: string;
    github?: string;
    linkedin?: string;
    twitter?: string;
    includeProjects?: boolean;
    includeBlog?: boolean;
    includeResume?: boolean;
}

export interface ToolArguments {
    query?: string;
    path?: string;
    config_content?: string;
    config_type?: string;
    feature?: string;
    level?: string;
    [key: string]: unknown;
}

Step 3: Create the Main Server

src/index.ts:

#!/usr/bin/env node

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { 
    CallToolRequestSchema, 
    ListToolsRequestSchema 
} from "@modelcontextprotocol/sdk/types.js";

// Initialize MCP Server
const server = new Server(
    {
        name: "renderer-mcp-server",
        version: "1.0.0",
    },
    {
        capabilities: {
            tools: {},
        },
    }
);

// Tool definitions
const TOOLS = [
    {
        name: "get_config_example",
        description: "Get example TOML configuration",
        inputSchema: {
            type: "object",
            properties: {
                config_type: {
                    type: "string",
                    enum: ["home", "projects", "blog", "resume", "social"],
                    description: "Type of configuration needed"
                }
            },
            required: ["config_type"]
        }
    },
    // ... more tools
];

// Handle tool listing
server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
}));

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;

    try {
        switch (name) {
            case "get_config_example":
                return getConfigExample(args.config_type);
            // ... more cases
            default:
                throw new Error(`Unknown tool: ${name}`);
        }
    } catch (error) {
        return {
            content: [{
                type: "text",
                text: `Error: ${error.message}`
            }],
            isError: true
        };
    }
});

// Start server
async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error("Renderer MCP Server running");
}

main().catch(console.error);

Step 4: Implement Tools

Tool 1: Configuration Examples

src/tools/examples.ts:

const CONFIG_EXAMPLES = {
    home: `# Home Page Configuration
[profile]
name = "Your Name"
tagline = "Your Role"
email = "your@email.com"

[hero]
title = "Hi, I'm Your Name 👋"
subtitle = "Building amazing things"
show_cta = true

[features]
show_about = true
show_skills = true
show_social = true

[theme]
mode = "auto"  # auto, light, dark
accent_color = "#0066cc"`,
    // ... more examples
};

export function getConfigExample(configType: string) {
    const example = CONFIG_EXAMPLES[configType];
    if (!example) {
        return {
            content: [{
                type: "text" as const,
                text: `Unknown config type: ${configType}`
            }],
            isError: true
        };
    }

    return {
        content: [{
            type: "text" as const,
            text: `# ${configType} Configuration Example\n\n\`\`\`toml\n${example}\n\`\`\``
        }]
    };
}

Tool 2: TOML Validator

src/tools/validator.ts:

import { parse as parseToml } from "toml";

export function validateTomlConfig(
    configContent: string, 
    configType: string
) {
    try {
        // Parse TOML
        const parsed = parseToml(configContent);

        // Validate based on type
        const issues: string[] = [];

        switch (configType) {
            case "home":
                if (!parsed.profile) issues.push("Missing 'profile' section");
                if (!parsed.hero) issues.push("Missing 'hero' section");
                break;
            case "projects":
                if (!Array.isArray(parsed.projects)) {
                    issues.push("Missing or invalid 'projects' array");
                }
                break;
            // ... more validations
        }

        if (issues.length === 0) {
            return {
                content: [{
                    type: "text" as const,
                    text: `✅ Valid!\n\nParsed:\n\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``
                }]
            };
        } else {
            return {
                content: [{
                    type: "text" as const,
                    text: `⚠️ Issues:\n${issues.map(i => `- ${i}`).join('\n')}`
                }]
            };
        }
    } catch (error) {
        return {
            content: [{
                type: "text" as const,
                text: `❌ TOML Syntax Error:\n${error.message}`
            }],
            isError: true
        };
    }
}

Tool 3: Template Generator

src/tools/template.ts:

export function generateStarterTemplate(options: TemplateOptions) {
    const { name, email, github, includeProjects, includeBlog } = options;

    const homeConfig = `[profile]
name = "${name}"
tagline = "Developer & Creator"
${email ? `email = "${email}"` : '# email = "your@email.com"'}

[hero]
title = "Hi, I'm ${name.split(' ')[0]} 👋"
subtitle = "Building amazing things"
show_cta = true
cta_text = "View My Work"
cta_link = "${includeProjects ? '/projects.html' : '#'}"`;

    const socialConfig = `[social]
${github ? `github = "${github}"` : '# github = "username"'}
${email ? `email = "${email}"` : '# email = "your@email.com"'}

[social.settings]
show_icons = true
open_in_new_tab = true`;

    return {
        content: [{
            type: "text" as const,
            text: `# Generated Configuration\n\n## home.toml\n\`\`\`toml\n${homeConfig}\n\`\`\`\n\n## social.toml\n\`\`\`toml\n${socialConfig}\n\`\`\``
        }]
    };
}

Tool 4: GitHub Integration

src/github.ts:

import { Octokit } from "@octokit/rest";

let octokit: Octokit | null = null;

export function initGitHub(token?: string) {
    octokit = new Octokit({
        auth: token || process.env.GITHUB_TOKEN
    });
}

export async function getRendererFile(path: string) {
    if (!octokit) throw new Error("GitHub not initialized");

    const { data } = await octokit.repos.getContent({
        owner: "NishikantaRay",
        repo: "renderer",
        path,
        ref: "main"
    });

    if (!("content" in data)) {
        throw new Error("Not a file");
    }

    const content = Buffer.from(data.content, "base64").toString();

    return {
        content: [{
            type: "text" as const,
            text: `# ${path}\n\n\`\`\`\n${content}\n\`\`\``
        }]
    };
}

Step 5: Build & Package

package.json:

{
  "name": "renderer-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "renderer-mcp": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod +x build/index.js",
    "watch": "tsc --watch"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4",
    "@octokit/rest": "^20.0.2",
    "toml": "^3.0.0"
  }
}

Build it:

npm run build
npm link  # For local testing

Testing with Claude Desktop

Claude Desktop has native MCP support built-in. Here's how to use it:

Step 1: Install Claude Desktop

Download from: https://claude.ai/download

Available for macOS and Windows.

Step 2: Configure MCP Server

Find your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your server:

{
  "mcpServers": {
    "renderer": {
      "command": "renderer-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here_optional"
      }
    }
  }
}

Why the GitHub token?

Without: 60 API requests/hour
With: 5000 API requests/hour
Get one at: https://github.com/settings/tokens

Step 3: Restart Claude Desktop

Close and reopen the app. The MCP server will start automatically.

Step 4: Verify Connection

In Claude Desktop, you should see:

A small "🔌" icon or "MCP" indicator
"Renderer" listed in connected tools

Step 5: Start Using It!

Just talk to Claude naturally. Here are real examples:

Example 1: Generate Starter Template

You:

Create a portfolio starter template for me. 
My name is John Doe, GitHub is johndoe, 
and I want projects and resume sections.

Claude (using MCP):

I'll generate a complete starter template for you using the 
Renderer MCP server.

*calls generate_starter_template tool*

Here's your customized configuration:

[Shows complete TOML configs for home.toml, social.toml, 
projects.toml, and resume.toml with your information pre-filled]

To use this:
1. Clone the Renderer repository
2. Copy these configs to the config/ directory
3. Run npm install && npm run dev
4. Your portfolio will be live at localhost:3000!

Example 2: Validate Configuration

You:

Can you validate this TOML config for me?

[profile]
name = "Jane Smith"
tagline = "Full Stack Developer"

[hero]
title = "Hi, I'm Jane"

Claude (using MCP):

Let me validate that for you.

*calls validate_toml_config tool*

⚠️ Configuration Issues Found:

1. Missing 'hero.subtitle' field (recommended)
2. Missing 'hero.show_cta' field (required)
3. Missing 'features' section

Here's the corrected version:

[profile]
name = "Jane Smith"
tagline = "Full Stack Developer"

[hero]
title = "Hi, I'm Jane"
subtitle = "Building amazing web applications"
show_cta = true
cta_text = "View My Work"
cta_link = "/projects.html"

[features]
show_about = true
show_skills = true
show_social = true

Example 3: Learn Features

You:

How do I add dark mode to my Renderer portfolio?

Claude (using MCP):

Let me search for that feature.

*calls search_renderer_features tool*

# Dark Mode in Renderer

Renderer includes automatic dark mode support!

## Configuration (config/home.toml)

[theme]
mode = "auto"  # Options: auto, light, dark
accent_color = "#0066cc"

## How it works:

- **auto**: Follows system preferences (recommended)
- **light**: Always light theme
- **dark**: Always dark theme

Users can also toggle themes manually with the theme 
switcher button that appears automatically.

The theme preference is saved in localStorage, so it 
persists across sessions.

Example 4: Get Examples

You:

Show me an example of how to configure projects

Claude (using MCP):

*calls get_config_example tool*

Here's a complete example for projects.toml:

# Projects Configuration

[[projects]]
title = "Renderer Framework"
description = "A TOML-driven portfolio system"
tags = ["JavaScript", "TOML", "HTML"]
repo = "https://github.com/username/renderer"
demo = "https://demo.example.com"
docs = "https://docs.example.com"
featured = true
company = "@MyCompany"

[[projects]]
title = "Another Cool Project"
description = "Building something awesome"
tags = ["TypeScript", "React", "Node.js"]
repo = "https://github.com/username/project"
featured = false

## Usage:
1. Copy this to config/projects.toml
2. Customize with your projects
3. Add more [[projects]] blocks as needed

Real Workflow Example

Here's a complete real-world workflow:

User: "I want to create a portfolio. Help me get started."

Claude: "I'll help you create a portfolio with Renderer! First, let me generate a starter template."

Uses generate_starter_template

Claude: "Great! I've created custom configurations for you. Now let me show you the setup steps."

Uses get_setup_guide

Claude: "Here's what to do:

Clone the repository...
Copy these configs...
Run these commands..."

User: "I added my projects but getting an error"

Claude: "Let me validate your configuration."

Uses validate_toml_config

Claude: "Found the issue! You're missing a comma on line 5. Here's the corrected version..."

User: "How do I deploy this?"

Uses get_setup_guide with level: "advanced"

Claude: "Here are your deployment options:

GitHub Pages...
Vercel (recommended)...
Netlify..."

Testing with MCP Inspector

The MCP Inspector is a visual debugging tool for MCP servers.

Step 1: Install & Launch

# Run the inspector (no installation needed)
npx @modelcontextprotocol/inspector renderer-mcp

This will:

Start your MCP server
Launch a web interface
Open your browser automatically

Step 2: Explore the Interface

The inspector has three panels:

┌──────────────────────────────────────────────────────┐
│  Left Panel       │  Center Panel    │  Right Panel  │
│  (Tools List)     │  (Input Form)    │  (Results)    │
├──────────────────────────────────────────────────────┤
│                                                        │
│  • Tool 1         │  [Input fields]  │  [JSON        │
│  • Tool 2         │  [for selected]  │   Response]   │
│  • Tool 3         │  [tool]          │               │
│  • ...            │                  │               │
│                   │  [Execute Btn]   │  [Formatted   │
│                   │                  │   Output]     │
└──────────────────────────────────────────────────────┘

Step 3: Test Each Tool

Test 1: Get Configuration Example

Left Panel: Click get_config_example
Center Panel:
- Field: config_type
- Value: home
Click: "Execute" button
Right Panel: Should show:

# Home Page Configuration Example

[profile]
name = "John Doe"
tagline = "Full Stack Developer"
...

Test 2: Validate Configuration

Left Panel: Click validate_toml_config
Center Panel:
- Field: config_content
- Value:
```
 [profile]
 name = "Test"
```

Field: config_type
Value: home
1. Click: "Execute"
2. Right Panel: Should show validation results

Try Invalid TOML:

[profile
name = "Missing bracket"

Should see syntax error with helpful message!

Test 3: Generate Template

Left Panel: Click generate_starter_template
Center Panel:
- name: "Alice Johnson"
- email: "alice@example.com"
- github: "alicejohnson"
- include_projects: ✅ true
- include_blog: ❌ false
- include_resume: ✅ true
Click: "Execute"
Right Panel: Should show complete template

Test 4: Search Features

Left Panel: Click search_renderer_features
Center Panel:
- feature: "analytics"
Click: "Execute"
Right Panel: Should show feature documentation

Step 4: Verify All Tools

Test all 8 tools systematically:

#	Tool Name	Test Input	Expected Output
1	`explore_renderer_docs`	query: "TOML"	Documentation snippets
2	`get_renderer_file`	path: "config/home.toml"	File contents
3	`list_renderer_files`	path: "config"	Directory listing
4	`validate_toml_config`	Valid TOML + type	✅ Valid message
5	`generate_starter_template`	name: "Test"	Full template
6	`get_config_example`	type: "projects"	Example config
7	`search_renderer_features`	feature: "dark mode"	Feature docs
8	`get_setup_guide`	level: "beginner"	Setup guide

Step 5: Debug Issues

Common Issues:

Tools Not Appearing

Problem: Left panel is empty
Solution: Check terminal for error messages
         Ensure server started successfully

Execution Fails

Problem: Error in right panel
Solution: Check input types match schema
         Verify required fields are filled

Slow Responses

Problem: Long wait times
Solution: Normal for GitHub API calls
         Add GitHub token for better performance

Step 6: Advanced Testing

Test Error Handling

Invalid config type:

{
  "config_type": "invalid_type"
}

Should return clear error message.

Missing required field:

{
  "name": null
}

Should indicate missing required field.

Test Edge Cases

Empty strings:

{
  "query": ""
}

Very long input:

{
  "config_content": "... 10,000 characters ..."
}

Special characters:

{
  "name": "Test<script>alert('xss')</script>"
}

Step 7: Performance Testing

Monitor the Network tab in browser DevTools:

Tool execution time
Response size
Error rates

Good benchmarks:

Simple tools: <200ms
GitHub API calls: <2s
Complex operations: <5s

Real-World Use Cases

Let's see how users actually use Renderer MCP Server:

Use Case 1: First-Time Portfolio Creation

Scenario: Sarah, a bootcamp graduate, needs a portfolio fast.

Traditional Way (2+ hours):

Find Renderer documentation
Read through all docs
Understand TOML syntax
Create configuration files
Debug syntax errors
Test locally
Deploy

With MCP (15 minutes):

Sarah: "Create a portfolio for Sarah Chen, full-stack developer, 
       GitHub sarahchen"

Claude: *generates complete template*

Sarah: *copies configs, runs npm install*

Sarah: "How do I deploy this?"

Claude: *provides deployment guide*

Sarah: *deploys to Vercel in 3 clicks*

Result: Portfolio live in 15 minutes! ✅

Use Case 2: Configuration Debugging

Scenario: Mike's portfolio won't load after config changes.

Traditional Way:

Console shows cryptic error
Search through documentation
Check TOML syntax manually
Trial and error fixes
Search Stack Overflow

With MCP:

Mike: "My portfolio broke after I updated config. Can you check it?"
      [pastes config]

Claude: *validates config*
        "Found 2 issues:
         1. Missing closing bracket on line 12
         2. Invalid value for 'mode' field (must be 'auto', 'light', or 'dark')

         Here's the corrected version..."

Mike: *copies fix, portfolio works immediately*

Result: Issue fixed in 2 minutes! ✅

Use Case 3: Feature Discovery

Scenario: Emma wants to add advanced features but doesn't know what's available.

Traditional Way:

Read through all documentation
Browse example repositories
Search issues and discussions
Trial and error implementation

With MCP:

Emma: "What features can I add to my portfolio?"

Claude: *lists features with descriptions*
        "Renderer has these features:
         - Dark mode theme switching
         - @mention system for companies
         - Analytics dashboard
         - Blog with MDX support
         - Project filtering by tags
         - Resume with timeline
         - And more!

         Which would you like to implement?"

Emma: "Tell me about the analytics dashboard"

Claude: *searches features*
        "The analytics dashboard shows:
         - Project view counts
         - GitHub stars
         - Visitor metrics
         - Performance stats

         Here's how to enable it..."

Result: Discovered and implemented features quickly! ✅

Use Case 4: Team Onboarding

Scenario: Tech startup needs to create portfolios for 10 developers.

Without MCP:

Each person spends 2-4 hours
Inconsistent results
Multiple support requests
Total: 20-40 person-hours

With MCP:

Template: "Generate template for [name], GitHub [username], 
          email [email], include projects and resume"

Each Developer:
1. Ask MCP for template (2 min)
2. Clone and setup (5 min)
3. Customize (10 min)
4. Deploy (3 min)

Total per person: 20 minutes
Total team: 3.5 hours (vs 20-40 hours)

Result: 85-90% time savings! ✅

Lessons Learned

After building and deploying Renderer MCP Server, here are key insights:

What Worked Well ✅

1. Modular Architecture

Each tool in its own file
Easy to add new tools
Simple to maintain and test
Clean separation of concerns

2. TypeScript

Caught errors at compile time
Great IDE autocomplete
Self-documenting code
Easier refactoring

3. stdio Transport

Simple setup
No networking complexity
Universal compatibility
Easy debugging

4. Comprehensive Examples

Users love copy-paste examples
Reduces support burden
Speeds up adoption
Encourages best practices

What Could Be Better 🔄

1. Caching

// Current: Every request hits GitHub API
// Better: Cache responses for repeated queries

const cache = new Map();
async function getCachedFile(path) {
    if (cache.has(path)) return cache.get(path);
    const result = await fetchFromGitHub(path);
    cache.set(path, result);
    return result;
}

2. Error Messages

// Current: Generic error messages
// Better: Actionable, specific errors

// Instead of:
"Validation failed"

// Provide:
"Missing required field 'profile.name' in home.toml (line 5)"

3. Progress Indicators

// Current: Silent processing
// Better: Show progress for long operations

async function longOperation() {
    console.error("Fetching documentation...");
    const docs = await fetchDocs();
    console.error("Processing results...");
    return processDocs(docs);
}

Key Takeaways 💡

Start Simple - MVP with core tools, iterate based on feedback
User-Centric - Solve real problems, not theoretical ones
Documentation - Clear examples > long explanations
Testing - Inspector + Claude Desktop = comprehensive testing
Community - Users will surprise you with use cases

Metrics That Matter 📊

After 1 month of Renderer MCP Server:

Metric	Before	After	Change
Avg Setup Time	2 hours	15 min	-87%
Support Tickets	50/week	15/week	-70%
Successful Setups	60%	95%	+58%
User Satisfaction	3.5★	4.7★	+34%
GitHub Stars	150	420	+180%

What's Next

Phase 2: Enhancements (Q1 2026)

Caching Layer

// Smart caching for GitHub responses
// Reduce API calls by 80%
// Faster response times

Offline Mode

// Work without internet
// Cached documentation
// Local validation

Better Error Messages

// Line numbers in errors
// Suggested fixes
// Related documentation links

Phase 3: Advanced Features (Q2 2026)

Visual Configuration Builder

GUI for creating configs
Drag-and-drop interface
Live preview
Export to TOML

AI Content Generation

Generate project descriptions
Write portfolio copy
Create blog post outlines
SEO optimization

Deployment Assistant

One-command deployment
Multiple platforms
Environment setup
Domain configuration

Phase 4: Ecosystem (Q3 2026)

Plugin System

// Let community create tools
interface Plugin {
    name: string;
    tools: Tool[];
    onLoad: () => void;
}

Marketplace

Share templates
Community plugins
Premium themes
Integrations

Multi-Language Support

i18n for documentation
Localized examples
Regional templates

Getting Started

Ready to try Renderer MCP Server?

Quick Start (5 Minutes)

# 1. Install
npm install -g renderer-mcp-server

# 2. Configure Claude Desktop
# Add to claude_desktop_config.json:
{
  "mcpServers": {
    "renderer": {
      "command": "renderer-mcp"
    }
  }
}

# 3. Restart Claude Desktop

# 4. Start using it!
# Just ask Claude: "Create a portfolio for me"

Build Your Own MCP Server

Want to create an MCP server for your project?

1. Clone the template:

git clone https://github.com/NishikantaRay/renderer-mcp-server
cd renderer-mcp-server

2. Customize for your use case:

Replace Renderer-specific logic
Add your own tools
Connect to your APIs

3. Test and deploy:

npm run build
npm link
npx @modelcontextprotocol/inspector your-mcp-server

Resources

GitHub: renderer-mcp-server
Renderer Framework: renderer
MCP Docs: modelcontextprotocol.io
Claude Desktop: claude.ai/download

Conclusion

Building Renderer MCP Server transformed how users interact with the Renderer framework. What was once a 2-hour manual process is now a 15-minute conversation with an AI assistant.

Key Achievements:

⚡ 87% faster setup time
🎯 95% success rate for first-time users
📉 70% reduction in support tickets
🌟 4.7★ user satisfaction
🚀 3x framework adoption growth

The Power of MCP:

MCP isn't just about connecting AI to tools—it's about creating intelligent assistants that truly understand your domain. The Renderer MCP Server doesn't just execute commands; it knows the framework intimately, validates configurations, teaches best practices, and guides users from zero to deployed.

This is the future of developer tools: AI assistants that are specialists, not generalists.

Your Turn:

What framework or tool could benefit from its own MCP server?

The pattern is proven. The infrastructure is here. The only limit is imagination.

Build something amazing. 🚀

About the Author

Nishikanta Ray is the creator of Renderer, a modern portfolio framework, and Renderer MCP Server. He's passionate about making web development more accessible through AI-powered tools.

GitHub: @NishikantaRay
Twitter: @nishikantaray
Website: nishikanta.in

Comments & Discussion

Have questions about building MCP servers? Share your experience in the comments!

Topics for discussion:

What tool/framework needs an MCP server?
Challenges you faced with MCP
Creative use cases you've discovered
Features you'd like to see

Let's build the future of AI-assisted development together! 💬

Tags: #MCP #AI #DeveloperTools #Anthropic #Claude #OpenSource #TypeScript #Portfolio

Published: December 29, 2025

Reading Time: 25 minutes

Last Updated: December 29, 2025

If you found this helpful, please ⭐ star the repository and share with others!

Behind the Scenes — Building NexoDrive and Reinventing File Sharing

Nishikanta Ray — Fri, 28 Nov 2025 18:54:41 +0000

Over the past few weeks, we (I and @Sumeet Naik ) built something. A simple tool that turns chaotic Google Drives into clean, user-friendly libraries.

We call it NexoDrive.

But this post isn’t just a product announcement — it’s the story behind why we built it and how it solves a surprisingly common problem.

The Pain Point: “Where’s the File?”

Whether you're building software, running a business, or studying in college — you’ve probably heard (or said):

“Can you resend the link?”
“I can’t find the file.”
“Where did you put this?”
“Do I need permission?”

Google Drive is powerful, but for sharing large sets of files, it falls apart fast.

People struggle to navigate deep folder structures.

Permission management becomes a nightmare.

Links get mixed up.

You spend more time helping people find files than actually working.

We ran into this problem while building a notes-sharing platform for a college. With 1,500+ users, Drive chaos became a daily issue.

So we built a solution.

The Idea: A Display Layer for Google Drive

We didn’t want to replace Drive.

Drive is great for storage.

We wanted to replace how people view your Drive.

The concept of NexoDrive became clear:

The owner stores everything in Google Drive (just like always)
NexoDrive reads the Drive using read-only access
We index everything and create a clean interface
End users can browse files instantly without touching Google Drive

A simple idea — but incredibly effective.

Security First

When someone hears “access to your Drive,” it’s natural to worry.

So from day one, we designed NexoDrive to be safe:

Only read-only access (no editing, deleting, downloading, or moving files)
You choose exactly what to show
Your Drive stays untouched
All indexing is internal and controlled

Your privacy stays intact.

What the User Sees

This is the magic.

Instead of the messy Google Drive UI, they get:

Clean file lists
Search
Instant loading
No login needed (unless you want it)
Only the files you choose to display

It looks like a custom-built resource library — without you needing to build anything.

Early Feedback

When we deployed this for the college platform:

💬 Students said: “Finally, everything is easy to find.”

💬 Teachers said: “We don’t have to manage permissions anymore.”

💬 Admins said: “This saves hours every week.”

That’s when we realized the potential.

Who This Is For

NexoDrive can help:

Educational institutions
Freelancers & agencies
Coaches & mentors
Businesses sharing documents
Creators delivering files
Teams with shared resources
Communities hosting notes/materials

If your Google Drive is the heart of your workflow, NexoDrive becomes the face of it.

Try It Out

We’ve launched our public beta here:

👉 https://nexodrive.xyz

This is just version 1. We have big plans for:

Custom branding
Analytics
Access control
Better search
Multi-account support
Embeddable file viewers

If you have ideas, feedback, or feature requests — we’d love to hear them.

Thanks for reading, and welcome to the beginning of a much cleaner file-sharing experience. 🚀

Master–Slave (Primary–Replica) Replication

Nishikanta Ray — Fri, 28 Nov 2025 18:39:16 +0000

If you’re building a modern application that needs speed, availability, and fault tolerance, MongoDB replication is one of the easiest and most powerful features you can use.

📌 What Is Master–Slave (Primary–Replica) Replication?

Replication ensures you have multiple copies of your data across different servers.

In MongoDB:

The Primary node handles all writes.
Secondary nodes replicate data from the primary and handle reads (optional).
If the primary fails, MongoDB automatically promotes a secondary → new primary.

This setup is known as a Replica Set, which is MongoDB’s improved version of the old master–slave architecture.

⭐ Why Do We Need Master–Slave (Primary–Replica) Architecture?

Master–slave replication exists because one single database server cannot handle everything reliably, efficiently, and safely. Splitting responsibilities between a master (primary) and slaves (replicas) solves several real-world problems.

📐 MongoDB Replication Architecture

            +-----------------+
            |     Primary     | <--- Write & Read
            +-----------------+
               /         \
              /           \
+-----------------+   +-----------------+
|   Secondary 1   |   |   Secondary 2   |
+-----------------+   +-----------------+
     Read Only            Read Only

⭐ What Is Slave Replication (Explained Like You’re 5)

Slave replication means:

One database is the master → accepts all writes
Other databases are slaves/replicas → copy whatever master does
Replicas stay almost up-to-date with the master

Think of it like a teacher (master) writing on the board, and

3 students (slaves/replicas) copying everything in real time.

Sometimes students copy late → this is replication lag.

🔁 How Slave Replication Actually Works (Technical Flow)

Below is the internal flow, no fluff:

1. Master records every write into a log

MySQL → Binary Log (binlog)
MongoDB → Oplog
PostgreSQL → WAL Log

Example log entry:

UPDATE products SET stock = 50 WHERE id = 101

2. Slaves read these logs continuously

A slave says:

➡️ “Master, give me the next log entry after position X.”

3. Slaves apply the changes locally

Whatever operation appears in the log:

INSERT
UPDATE
DELETE

…slaves replay them in the same order.

4. After applying logs → slave becomes synced

This cycle repeats non-stop.

⏳ Replication Delay (Lag): Why It Happens

Slaves may fall behind due to:

Slow network
Heavy load on slave
Large write burst on master
Slow disk I/O
Complex queries running on slave

When the slave is behind, it shows old data temporarily.

🛠️ How Systems Handle Delays

1️⃣ Read-from-master for critical operations

Apps often use:

Normal read → from replica (fast)
Critical read (e.g., after update) → from master

This avoids stale data issues.

2️⃣ “Read-your-own-write” rules

If a user writes something (POST/UPDATE):

You route that user’s next read to the master only
Until replica catches up

Frameworks like Rails, Laravel, Django already support this.

3️⃣ Monitoring replication lag

Tools measure:

replication_lag = slave_last_applied_timestamp - master_timestamp

If lag > X seconds:

→ temporarily stop sending reads to that replica

4️⃣ Write concerns (MongoDB)

MongoDB allows:

{ writeConcern: { w: "majority" } }

Meaning:

→ Write is successful only when most replicas have it

This reduces risk of data inconsistency.

5️⃣ Semi-Sync Replication (MySQL / PostgreSQL)

Master waits until at least one slave confirms:

“Yep, I received the log.”

This avoids data loss.

🔄 How Updates Flow (Example With Steps)

Let’s use a real example:

A user updates their profile:

UPDATE users SET name='Nishikanta' WHERE id=5;

Here’s what happens:

Step 1 — Master writes to its DB

Master updates row in its storage engine.

Step 2 — Master logs the change

Master adds entry to binlog/oplog:

{ op: "update", id: 5, name: "Nishikanta" }

Step 3 — Slaves fetch this log

Replica 1 → “Give me log #520”

Replica 2 → “Give me log #520”

Master streams them.

Step 4 — Slaves apply changes

Replica updates:

id=5 → name=Nishikanta

Step 5 — Replicas catch up

Once all logs are applied → they’re in sync.

📊 Diagram: How Replication Works (Clean + Blog-Ready)

                ┌───────────────────────┐
                │       MASTER          │
                │ (Primary - All Writes)│
                └───────┬───────────────┘
                        │
        Writes → Binlog/Oplog generated
                        │
        ┌───────────────┴───────────────┐
        │                               │
┌────────────────────┐        ┌────────────────────┐
│    SLAVE #1        │        │    SLAVE #2        │
│ (Replica - Reads)  │        │ (Replica - Reads)  │
└───────┬────────────┘        └──────────┬─────────┘
        │                                 │
        │    Fetch log continuously       │
        │        Apply updates            │
        │     Handle replication lag      │
        ▼                                 ▼
  Up-to-date copy of DB            Up-to-date copy of DB

🟩 Conclusion

Master–slave (primary–replica) replication is one of the most essential techniques for building fast, reliable, and highly available modern applications. By separating write operations to the master and distributing read operations across multiple replicas, systems can handle far more traffic, avoid downtime, and guarantee that data remains safe even if a server fails.

Although replication may introduce small delays (replication lag), most real-world systems manage this easily through smart routing, read-after-write strategies, and monitoring tools. The result is a database architecture that provides scalability, resilience, and real-time data redundancy — all without changing how your application writes data.

Whether you’re using MongoDB, MySQL, PostgreSQL, or Redis, mastering replication is a core skill that enables you to build applications that stay fast, stay online, and scale gracefully as your users grow.