DEV Community: Gaurav Kumar Singh

The Secret Debugging Tool You're Not Using

Gaurav Kumar Singh — Sun, 26 Jul 2026 06:22:32 +0000

We’ve all been there: It’s 11 PM, the bug is still alive, your tests are failing, and you’re about to throw your laptop out the window.

We usually view debugging as a pure logic problem: stack traces, breakpoints, and logs. But Emotional Intelligence (EQ) is often the real reason you fix a bug in 20 minutes instead of 3 hours.

Here is how EQ actually applies to your daily workflow:

1. Spotting Tunnel Vision Before It Wastes Your Time

Frustration causes confirmation bias. You start forcing your initial hypothesis ("It MUST be the cache!") even when the logs say otherwise.

EQ Move: Recognize physical signs like tight shoulders or rage-typing. Take a 5-minute bio-break. Stepping away resets your mental stack, which is usually faster than another hour of blind grinding.

2. Separating `code.hasBug()` from `dev.isBad()`

A stubborn bug easily triggers imposter syndrome: "A senior dev would have solved this already." That inner voice just adds noise to your debugging stack.

EQ Move: Reframe the problem objectively:
- ❌ "I don't know what I'm doing." (Emotion)
- ✅ "This async function isn't returning the expected payload." (Fact)

Debug the code, not your self-worth.

3. Handling Spicy Bug Reports

A ticket comes in: "This is completely broken, who let this ship?!" Your gut reaction might be to get defensive or send a passive-aggressive response.

EQ Move: Filter out the noise. Translate panic or bad phrasing into actionable facts. Reply calmly to de-escalate, pull the missing repro steps, and ship the fix without unnecessary Slack drama.

4. Rubber Ducking and Asking for Help (Ego-Free)

How many times have you fixed a bug just by explaining it out loud to a peer? Sitting in silent frustration for hours doesn't make you a hero; it just delays the feature.

EQ Move: Treat asking for help as an optimization tactic. Send a concise message with context: > "Hey, expecting X, getting Y. Already tried A and B. Got 5 mins to glance at this snippet?"

5. Staying Cool During Prod Outages

Panicked devs make bad hotfixes and type typos straight into production consoles.

EQ Move: The calmest dev in the room becomes the effective incident commander. Slow down, verify facts before firing off commands, and keep communication clear. Clear heads drop downtime.

TL;DR

Debugging isn't just Dev vs. Code—it’s Dev vs. Emotional Reactivity. The fastest problem solvers aren't always the ones who memorized the entire language spec. They’re the ones who catch their frustration early, communicate clearly under pressure, and keep their head clear.

Next time you get stuck, ask yourself: "Am I debugging the system, or am I debugging my mood?" Fix the mood first, and the logic gets a lot easier to trace.

The Most Critical Architecture in Tech: Psychological Safety

Gaurav Kumar Singh — Fri, 17 Jul 2026 12:19:11 +0000

Every engineer knows that sudden, cold dread when a production build breaks. But what happens after the break tells you everything about your engineering culture. If the first instinct is to find someone to blame, your team has a critical bug in its foundation — and no amount of CI/CD tooling will patch it.

Psychological safety isn't an HR buzzword. It's a technical property of the system, as real as uptime or test coverage. It's the human try/catch block that keeps a team resilient under failure. Strip it out, and innovation stalls, code quality degrades, and tech debt quietly compounds until the whole thing collapses under its own weight.

Why Psychological Safety Is a Codebase Concern

When engineers are afraid of looking incompetent, they don't just feel bad — they ship worse software. That fear propagates directly into the codebase in a few predictable ways:

Silent outages, slow recovery. When people fear reprimand, they hide mistakes, delay escalating bugs, or slap a quick patch over the symptom instead of digging into the root cause. Teams with high safety run blameless postmortems that ask how the system failed, never who failed it — and they recover faster because of it.
Tech debt that never gets paid down. When failure isn't safe, people stop taking risks. Nobody volunteers to refactor the legacy monolith if a resulting bug could show up in their performance review. Teams default to "fragile but predictable" over "robust but risky," and the debt just piles up.
Pull requests as combat instead of collaboration. In low-safety environments, code review stops being a shared search for edge cases and turns into something to survive.

The data behind it: When Google ran Project Aristotle to find out what made their best teams tick, they looked at everything — educational background, personality types, seniority mix. The answer had almost nothing to do with who was on the team and everything to do with how they treated each other. Psychological safety came out as the single strongest predictor of team performance, ahead of every other factor they measured.

Anti-Patterns That Quietly Rot Team Culture

Just like code smells, these are easy to miss day-to-day but corrosive over time:

The brilliant jerk. A highly skilled developer who belittles others in reviews or design discussions. Tolerating this — even because they "ship fast" — tells the rest of the team that output matters more than how people are treated.
Weaponized nit: comments. Nitpicks used to assert dominance in a PR rather than to actually improve the code. The tell is volume and tone: constructive nitpicking is occasional and specific; weaponized nitpicking is constant and personal.
Treating bugs as personal failure. An unhandled exception in prod is a gap in your test suite, not a character flaw in whoever wrote the line. Teams that internalize this stop hiding bugs and start writing tests for them.

Engineering a Safer Culture

Safety doesn't happen by accident — it's a design pattern, and it takes the same intentionality as any other piece of architecture.

1. Model vulnerability from the top

Leads and staff engineers need to actually say "I don't know," "I was wrong," and "I need help here" — out loud, in public channels, not just in 1:1s. When a senior engineer tells the story of the time they dropped a production database, it gives everyone else permission to be human.

2. Critique the code, not the person

This is the single highest-leverage habit for review culture, and it's a small rewrite:

- Your code is inefficient here.
+ Let's look at the time complexity of this loop — if the dataset
+ grows, we might hit a bottleneck. What do you think about a Map
+ instead of nested iteration?

Same technical point, zero identity attached to it. The reviewer isn't softening the feedback — the feedback is exactly as direct. It's just aimed at the loop instead of the person who wrote it.

3. Kill the async anxiety loop

In remote and hybrid teams, a context-free message is its own kind of memory leak — it sits in someone's head consuming cycles until it's resolved.

- We need to talk about your PR.
+ Hey, I left a couple of architecture questions on your PR —
+ no rush, let's chat about options at tomorrow's sync 👍

The fix costs one extra sentence. The anxiety it prevents can cost an afternoon of someone's focus.

The Bottom Line

We pour money into high availability, automated pipelines, and fault-tolerant infrastructure. But the most critical system any team runs is the human one underneath all of it. If your developers don't feel safe to fail, your software will eventually fail the same way — quietly, and in production.

Psychological safety isn't the soft stuff. It's the infrastructure everything else runs on.

How to Thrive (Not Just Survive) as a Developer in the Age of AI

Gaurav Kumar Singh — Sat, 11 Jul 2026 12:54:36 +0000

The narrative around Artificial Intelligence and software engineering has shifted dramatically. We are no longer asking if AI will change development, but rather how we change with it.

If your value as a developer is tied solely to how fast you can churn out boilerplate code, write standard API endpoints, or memorize syntax, the landscape is becoming challenging. AI can do those things in seconds. However, this isn't a death sentence for the engineering career—it is an evolution. The industry is moving away from pure "code generation" and shifting toward system architecture, integration, and governance.

To remain indispensable, you need to know exactly where to direct your energy and what pitfalls to avoid.

Where to Focus Your Energy

To stay relevant, you must position yourself in the areas where AI struggles: high-level abstraction, complex contextual reasoning, and human leadership.

1. System Design and Enterprise Architecture

AI is excellent at writing isolated functions, but it struggles with massive, interconnected systems. Focus on how components interact at scale. Understanding how to slice a monolithic application into resilient microservices, orchestrate microfrontends, or design cloud-native solutions is where the high-value work lies.

2. Code Governance and Quality Assurance

With AI generating code at unprecedented speeds, codebases are expanding faster than ever. The world doesn't just need people who can create code; it needs gatekeepers who can validate it. Your role will increasingly focus on setting quality standards, establishing robust CI/CD pipelines, and ensuring that AI-generated code adheres to strict security, compliance, and performance metrics.

3. Mentorship and Team Leadership

The influx of AI tools means junior engineers can produce code much earlier in their careers, but they often lack the foundational experience to spot subtle architectural flaws or security vulnerabilities. Senior developers must step up as leaders, guiding less experienced teammates on why certain architectural patterns matter, preventing burnout, and maintaining engineering discipline within the team.

4. Deep Systems and Performance Optimization

While AI can write functional code, it often writes resource-heavy or unoptimized code. Specializing in low-level systems programming, memory safety, and fine-tuning performance-critical applications gives you a massive edge. Knowing how to wring every ounce of efficiency out of a system remains a highly prized human skill.

What to Take Care of (The Pitfalls to Avoid)

Staying relevant isn't just about learning new skills—it's also about avoiding the bad habits that AI tools can induce.

The "Copilot Crutch" Warning: Relying too heavily on AI tools for basic problem-solving can cause your foundational engineering muscles to atrophy. If you don't understand the underlying logic of the code your AI assistant suggests, you cannot safely maintain or debug it when things break.

Watch out for Architectural Drift: AI generates code based on local context (the file you are working on). It doesn't inherently understand your entire organization's long-term technical roadmap or governance model. Left unchecked, AI-assisted development can lead to a bloated, fragmented codebase.
Don't skip the "Why": Always question AI suggestions. If a Large Language Model gives you an elegant solution, take a moment to understand why it works before accepting the pull request.
Guard your Domain Knowledge: Technical skills matter, but understanding the business logic and user experience is what converts code into a successful product. AI doesn't know your customers; you do.

The Evolution of the Developer Role

To visualize this shift, look at how the daily responsibilities of a resilient software engineer are changing:

Traditional Developer Focus	AI-Era Developer Focus
Writing boilerplate, configurations, and repetitive unit tests.	Designing system boundaries, security models, and data flows.
Memorizing language syntax and API frameworks.	Evaluating and integrating complex, multi-system dependencies.
Fixing syntax errors and basic debugging.	Auditing AI-generated code for hidden vulnerabilities and tech debt.
Functioning as an isolated individual contributor.	Acting as a technical leader, mentor, and strategic translator for business needs.

Moving Forward

The goal is to stop competing with AI at what it does best (speed and volume) and start leveraging it to do what humans do best (strategy, empathy, and holistic design). By shifting your mindset from being a "code writer" to a "software architect and custodian," you ensure that your skills remain not just relevant, but entirely essential to the future of technology.

Sick of App Store Ads? So I Built My Daughter Her Own Drawing PWA

Gaurav Kumar Singh — Thu, 02 Jul 2026 14:14:45 +0000

"Daddy, another ad?"

If you have young kids who use an iPad, you may know this problem.

Last week, my daughter was using a free drawing app. She was happy and busy making her art. But every few minutes, a loud ad came on the screen. She could not skip it. It stopped her drawing again and again.

After this happened many times, she looked at me and said:

"I just want to draw. Can we make our own app without ads?"

At first, I could have said that making an app takes too much time. But then I thought, why not try?

So we made it a small weekend project.

My daughter became the product boss. She asked for rainbow brushes, a big drawing space, fun sounds, and no pop-ups. I worked on the code.

Together, we built this:

unicorn-draw.vercel.app

The tool that helped us build it fast was Google AI Studio with Gemini.

The Tech Stack

I wanted the app to be easy to use on an iPad. I also did not want to deal with the App Store.

So I made it as a Progressive Web App, or PWA. This means it works like an app, but it runs in the browser.

Here is what I used:

HTML5 Canvas API for drawing
CSS for big buttons and bright colors
Service Worker so the app can work offline
Web App Manifest so it can be added to the home screen
Google AI Studio and Gemini to help write and improve the code

Because it is a PWA, my daughter can open it from the iPad home screen. It runs full screen. It has no ads, no tracking, and no hidden pop-ups.

Building with Google AI Studio

Google AI Studio made the work much faster.

First, I asked Gemini to make a simple drawing app using HTML5 canvas. I also asked it to support touch events, so it would work well on an iPad.

Then my daughter tested the first version. She quickly asked for a magic rainbow brush and a simple clear button.

I gave the code back to Gemini and asked it to add a rainbow brush. I also asked it to make the buttons look more fun for a drawing app.

After that, I used Gemini to help create the PWA files, like manifest.json and the service worker.

In a short time, the app started to feel like a real tablet app.

Source Code

The project is open source.

You can see the full code here:

GitHub Repository: gaurav101/unicorn-draw

How to Install It on an iPad or Phone

You can add the app to your home screen in a few seconds.

Open unicorn-draw.vercel.app in your browser.
On iPhone or iPad, tap the Share button. On Android, tap the three dots menu.
Tap "Add to Home Screen".
Open it from the home screen and start drawing.

Now your child has a simple drawing app with no ads.

What I Learned

1. AI Helps You Build Faster

Gemini did not just write code for me. It helped me move fast.

Instead of spending time on small setup work, I could focus on how the app should feel for my daughter.

The whole project took only a couple of hours.

2. Kids Can Learn That They Can Build Things

The best part was not the app.

The best part was seeing my daughter understand something important:

Technology is not something we only have to use. If something is annoying or broken, we can try to make a better version.

That was the real win.

Markdown to Styled HTML in Java

Gaurav Kumar Singh — Sun, 28 Jun 2026 08:22:14 +0000

If you have ever built a Java application that converts Markdown to HTML—whether for a blog engine, a documentation site, or user-generated comments—you have likely run into a frustrating roadblock.

You pull in a solid library like commonmark-java, pass your Markdown string, and get perfectly valid semantic HTML blocks. But then you render it on the frontend and realize it looks completely unstyled.

Modern CSS frameworks like Tailwind CSS, Bootstrap, or Bulma rely heavily on utility classes. They don't automatically style raw <h1>, <p>, or <blockquote> tags unless you wrap them in heavy global stylesheet overrides. To fix this in Java, you are usually forced to write verbose custom tag renderers, map complex attribute providers, or write messy string-replacement wrappers.

That is exactly the problem FluentMarkdown solves.

💡 What is FluentMarkdown?

FluentMarkdown is a lightweight, zero-boilerplate Java library built directly on top of commonmark-java. It introduces a clean, fluent API that automatically injects the proper CSS framework classes into your HTML elements during the parsing phase.

Instead of fighting your CSS framework, you can map your tags instantly using built-in presets or completely custom styles.

🛠️ Getting Started

1. Installation

The library is explicitly lightweight (only four core files) and requires Java 17 or later. You can add it via Maven:

<dependency>
    <groupId>io.github.gaurav101</groupId>
    <artifactId>fluentmarkdown</artifactId>
    <version>1.0.4</version>
</dependency>

2. Quick Start: Use a Framework Preset

If you use Tailwind, Bootstrap 5, or Bulma, FluentMarkdown has pre-mapped configurations ready to go.

Here is how easily you can render fully-styled Tailwind HTML:

import io.github.gaurav101.fluentmarkdown.Markdown;

public class App {
    public static void main(String[] args) {
        String markdown = "# Hello World\nThis is a paragraph.";

        // One fluent chain handles it all
        String tailwindHtml = Markdown.from(markdown)
                                      .withTailwind()
                                      .toHtml();

        System.out.println(tailwindHtml);
    }
}

Output:

<h1 class="text-4xl font-extrabold tracking-tight mb-4 mt-6">Hello World</h1>
<p class="mb-4 leading-relaxed text-base">This is a paragraph.</p>

Switching frameworks is as simple as swapping .withTailwind() for .withBootstrap() or .withBulma().

🧠 Advanced Usage

🔒 Step 3: XSS Protection (Safe Mode)

If you are processing untrusted user input (like blog comments), rendering raw HTML can expose your app to Cross-Site Scripting (XSS) attacks. FluentMarkdown includes a built-in .safe() modifier that strips out malicious inline scripts and raw HTML blocks seamlessly.

String unsafeInput = "<script>alert('hack')</script>\n\n# Safe Title";

String safeHtml = Markdown.from(unsafeInput)
                          .withTailwind()
                          .safe() // Strips dangerous HTML
                          .toHtml();

🎨 Step 4: Custom Style Configurations

Don't use a standard CSS framework? You can build an immutable StyleConfig to map your own internal design system classes to any HTML tag.

import io.github.gaurav101.fluentmarkdown.StyleConfig;

StyleConfig myCustomConfig = StyleConfig.builder()
        .tag("h1", "custom-main-title")
        .tag("p", "body-text text-muted")
        .tag("a", "global-link")
        .build();

String customHtml = Markdown.from(markdown)
                            .withStyle(myCustomConfig)
                            .toHtml();

🔄 Step 5: Extend Existing Presets

If you love the Tailwind preset but want to tweak just one or two elements (like changing the link color), you can merge and overwrite tags dynamically:

import io.github.gaurav101.fluentmarkdown.Presets;

StyleConfig modifiedTailwind = StyleConfig.builder()
        .mergeFrom(Presets.tailwind()) // Start with Tailwind defaults
        .tag("a", "text-indigo-600 underline") // Overwrite just the anchor tag
        .build();

🎯Conclusion

FluentMarkdown provides a highly practical solution to a common backend UI problem. It keeps your Java code clean, readable, and perfectly married to modern frontend utilities.

Give the project a look, try it out in your next Java project, and don't forget to drop a ⭐️ on the repository!

👉 GitHub Repository: gaurav101/FluentMarkdown

The Hidden Cost of the AI Hype

Gaurav Kumar Singh — Thu, 25 Jun 2026 15:55:00 +0000

We talk a lot about what AI can build.

Code generation. Faster prototypes. Automated debugging. One-shot apps. Entire products created in hours.

And yes, AI is powerful.

But there is a quieter cost we are not talking about enough:

AI hype is starting to weaken the motivation to learn core engineering deeply.

That should worry us.

1. The "Why Bother?" Mindset

When the dominant narrative says AI can generate code instantly, many engineers start asking:

Why should I spend months mastering frameworks, architecture, databases, networking, or system design?

At first, that sounds practical. If a tool can help, why not use it?

But there is a difference between using AI to move faster and using AI to avoid understanding.

Core engineering is not just about writing code. It is about knowing why something works, where it breaks, how it scales, and how to fix it when the generated answer is wrong.

If we skip that learning, we create engineers who can prompt systems but cannot reason deeply about systems.

That is a dangerous tradeoff.

2. The Funding and Praise Monopoly

Right now, AI gets most of the attention.

Budgets move toward AI. Leadership praises AI initiatives. Teams are pushed to add AI features even when the fundamentals are still weak.

Meanwhile, excellent core engineering often goes unnoticed.

The people improving reliability, performance, developer experience, infrastructure, security, and maintainability are still doing high-impact work. But in many places, that work is being treated as less exciting simply because it is not branded as AI.

This creates pressure.

Engineers feel they must pivot to AI, not always out of interest, but out of fear. Fear of being left behind. Fear of being replaced. Fear that their existing expertise is no longer valued.

That is not innovation. That is anxiety disguised as progress.

3. The "AI-First" Discount

There is another subtle problem.

When someone builds something impressive today, the reaction is often:

AI probably generated that.

That assumption discounts real skill.

It ignores the planning, debugging, tradeoffs, refactoring, architecture, and judgment behind the work. AI may assist, but it does not automatically create good software.

Great engineering still requires taste. Context. Discipline. Experience. The ability to make hard decisions when requirements are messy and systems are complex.

When we assume every good output came from AI, we quietly devalue human craftsmanship.

AI Is an Accelerator, Not a Substitute

AI can help us move faster.

It can explain concepts, generate drafts, find bugs, write boilerplate, and help us explore ideas quickly.

But AI is not a replacement for engineering fundamentals.

If we stop learning the building blocks, we weaken the entire ecosystem AI depends on. Someone still needs to understand distributed systems. Someone still needs to design reliable APIs. Someone still needs to debug production failures at 2 AM. Someone still needs to know when the AI-generated solution is wrong.

The future should not be "AI instead of engineers."

It should be AI with stronger engineers.

What We Should Value

We need to keep rewarding the work that keeps technology stable:

Strong system design
Clean architecture
Reliable infrastructure
Secure software
Maintainable codebases
Deep debugging skills
Thoughtful technical leadership

AI can support this work, but it cannot replace the need for people who understand it deeply.

The best engineers of the future will not be the ones who blindly rely on AI.

They will be the ones who use AI wisely while continuing to sharpen their fundamentals.

So the real question is:

How are you balancing the AI push while keeping your core engineering skills sharp?

Let's discuss.

Building a Safe, Local AI Coding Agent with Node.js

Gaurav Kumar Singh — Fri, 19 Jun 2026 03:57:12 +0000

Welcome to the 4th article of the MCP and RAG with JS series.

In this article, we will learn what AI agents are by building a practical, beginner-friendly coding agent in JavaScript. We will use a locally running LLM, Mistral on Ollama.

You do not need any paid subscription or API key. Everything runs locally on your machine, so this is accessible for learning, testing, and experimenting.

What We Are Building

We are building a local personal coding agent.

It runs in the terminal and helps us understand a JavaScript project. It can:

list project files
read project files
search text
explain code
find possible bugs
propose code changes

The important safety rule is this:

The agent can inspect files, but it does not directly edit them. If it wants to change something, it only returns a patch proposal for a human developer to review.

So in simple words, we are building a small local coding assistant.

Why This Helps Us Learn

AI agents can sound complicated, but most agent systems use a few common patterns.

In this project, we will learn those patterns with plain JavaScript:

Agent loop: repeat until the model gives a final answer.
Tool calling: let the model request specific JavaScript functions.
Tool allowlist: only allow approved tools to run.
System prompt: tell the model how it should behave.
JSON action protocol: make the model respond with structured JSON.
Model adapter: keep the Ollama HTTP code in one small file.
Safety boundary: keep file access inside the project root.
Human-in-the-loop changes: propose patches instead of applying them.
Tests for safety: verify path traversal, large file, and missing file behavior.

These same ideas appear in larger AI-agent frameworks. This project keeps them small enough to understand.

The Big Idea

A normal chatbot usually works like this:

User asks question -> Model answers

An agent works more like this:

User asks question
  -> Model decides what to do
  -> JavaScript runs a safe tool
  -> Model sees the tool result
  -> Model answers

The model does not directly read your files or run commands. It asks for a tool, and your JavaScript code decides whether that tool is allowed.

That is the main idea behind this project.

Project Structure

You can explore and clone the complete codebase in the coding-agents GitHub repository.
The important files are:

.
|-- package.json
|-- src
|   |-- cli.js
|   |-- agent.js
|   |-- ollama.js
|   `-- tools.js
`-- test
    `-- tools.test.js

Each file has a clear job:

src/cli.js: terminal entry point
src/agent.js: agent loop and tool dispatch
src/ollama.js: local Ollama API client
src/tools.js: safe filesystem tools
test/tools.test.js: safety and tool behavior tests

1: CLI Entry Point

The app starts in src/cli.js.

It imports the agent:

import { runAgent } from "./agent.js";

Then it chooses the project root and model:

const root = options.root || process.cwd();
const model = options.model || process.env.OLLAMA_MODEL || "mistral";

This means:

use --root if the user provides it
otherwise use the current folder
use --model if provided
otherwise use OLLAMA_MODEL
otherwise use mistral

The CLI supports two modes.

One-shot mode:

npm start -- "Explain src/tools.js"

Interactive mode:

npm start

In both cases, the CLI eventually calls:

const answer = await runAgent({ goal, root, model, verbose });

So the CLI is only responsible for input and output. The real agent behavior lives in runAgent.

2: Agent Loop

The main function is in src/agent.js:

export async function runAgent({ goal, root, model, verbose = false }) {

At the start, it creates the available tools:

const { createTools } = await import("./tools.js");
const tools = createTools({ root });

Passing root is important. It tells the tools which folder they are allowed to inspect.

Then the agent creates a message history:

const messages = [
  {
    role: "system",
    content: buildSystemPrompt(tools)
  },
  {
    role: "user",
    content: goal
  }
];

The system message contains rules for the model. The user message contains the developer's request.

Then the agent runs a loop:

for (let step = 1; step <= MAX_STEPS; step += 1) {
  const prompt = renderPrompt(messages);
  const raw = await generateWithOllama({ prompt, model });
  const action = parseAction(raw);

  // final answer or tool call
}

MAX_STEPS is set to 8, so the agent cannot loop forever.

This loop is the heart of the agent:

messages -> prompt -> model -> action -> tool or final answer

3: System Prompt

The system prompt tells the model how to behave.

In this project, the prompt says the model should:

inspect files before making project-specific claims
never claim a patch was applied
use propose_patch only for suggested changes
return exactly one JSON object

It also describes the available tools:

const toolDescriptions = Object.entries(tools)
  .map(([name, tool]) => `- ${name}: ${tool.description} Parameters: ${JSON.stringify(tool.parameters)}`)
  .join("\n");

This lets the model know what it can ask for.

The model must respond in one of two shapes.

To call a tool:

{"type":"tool","name":"read_file","arguments":{"path":"src/example.js"}}

To finish:

{"type":"final","answer":"Your answer here."}

This is a simple JSON action protocol. It is easy to understand because there is no hidden framework magic.

4: Local Model Adapter

The file src/ollama.js keeps the Ollama API call separate from the rest of the app.

The default local URL is:

const DEFAULT_OLLAMA_URL = "http://127.0.0.1:11434";

The function sends the prompt to Ollama:

const response = await fetch(`${baseUrl}/api/generate`, {
  method: "POST",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model,
    prompt,
    stream: false,
    options: {
      temperature
    }
  })
});

Then it returns the model text:

const data = await response.json();
return data.response || "";

This file has one job:

prompt in -> Ollama HTTP request -> model response out

Keeping this in one file makes it easier to swap models later.

5: Tool Calling

After Ollama responds, the agent parses the response:

const action = parseAction(raw);

If the model gives a final answer, the agent returns it:

if (action.type === "final") {
  return action.answer;
}

If the model asks for a tool, the agent checks whether that tool exists:

const tool = tools[action.name];
if (!tool) {
  messages.push({
    role: "tool",
    content: JSON.stringify({
      error: `Unknown tool: ${action.name}`,
      allowedTools: Object.keys(tools)
    })
  });
  continue;
}

This is very important.

The model cannot invent tools. It can only use tools that exist in the local JavaScript object.

Then the agent runs the tool:

const result = await tool.run(action.arguments || {});

And sends the result back into the message history:

messages.push({
  role: "tool",
  content: JSON.stringify({
    tool: action.name,
    result
  })
});

Now the model can use real project information instead of guessing.

Example flow:

User: Explain src/tools.js
Model: calls read_file
JavaScript: reads the file safely
Model: sees the file content
Model: gives final explanation

6: Safe Tools

The tools live in src/tools.js.

The project has four tools:

list_files
read_file
search_text
propose_patch

Each tool has:

description: tells the model what it does
parameters: tells the model what arguments it accepts
run: the actual JavaScript function

Example shape:

read_file: {
  description: "Read a UTF-8 text file from inside the project root.",
  parameters: {
    path: "File path relative to project root."
  },
  run: async ({ path: filePath } = {}) => {
    // safe implementation
  }
}

The tools are intentionally narrow.

list_files lists files under the project root.

read_file reads one text file if it is safe and not too large.

search_text searches project files for a string or regex.

propose_patch returns a patch proposal, but does not apply it.

That last point matters. The model can suggest changes, but a human still reviews them.
** use a safe regex engine if you are planning to expose the agent to external user inputs. **

7: Path Safety With `safeResolve`

The most important safety function is:

export function safeResolve(root, requestedPath) {
  const absolute = path.resolve(root, requestedPath);
  const relative = path.relative(root, absolute);

  if (relative.startsWith("..") || path.isAbsolute(relative)) {
    throw new Error(`Path escapes project root: ${requestedPath}`);
  }

  return absolute;
}

This blocks path traversal.

For example, this should be allowed:

src/tools.js

But this should be blocked:

../outside.txt

Why?

Because the agent should only inspect the selected project folder. Model output is not trusted input, so every requested path goes through safeResolve.

This is one of the most important lessons in agent development:

Give the model useful tools, but put real safety checks in code.

8: Size Limits

The tool layer also avoids reading huge files:

const MAX_READ_BYTES = 80_000;
const MAX_SEARCH_FILE_BYTES = 250_000;

read_file throws an error if a file is too large.

search_text skips files that are too large.

This protects the model context and keeps the agent responsive.

9: Patch Proposals, Not Auto-Edits

The propose_patch tool returns:

{
  summary,
  patch,
  applied: false,
  note: "Patch proposal only. Review before applying."
}

This is a human-in-the-loop design.

The agent can help you think and propose changes, but it does not silently modify your files.

For a beginner agent, this is a good safety tradeoff.

10: Tests for Safety

The project uses Vitest.

From package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

The tests cover the dangerous parts:

safeResolve allows normal paths
safeResolve blocks ../ traversal
list_files handles missing directories
read_file rejects missing paths and directories
read_file rejects large files
search_text skips large files
propose_patch returns applied: false

Example traversal test:

expect(() => safeResolve(fixtureProjectRoot, "../outside.txt")).toThrow(/escapes project root/);

Example large-file test:

await expect(tools.read_file.run({ path: "large-read.txt" })).rejects.toThrow(/too large to read safely/);

Tests are not just for correctness here. They protect the safety boundary of the agent.

Complete Request Flow

If you run:

npm start -- "Explain src/tools.js"

the flow is:

src/cli.js receives the request.
It calls runAgent.
src/agent.js creates safe tools.
The system prompt describes the rules and tools.
src/ollama.js sends the prompt to local Ollama.
The model returns a JSON action.
If it asks for a tool, the agent checks the allowlist.
The tool runs with safety checks.
The tool result goes back to the model.
The model returns a final answer.

That is an AI agent in practical terms.

It is an LLM connected to a controlled loop, safe tools, and clear rules.

How to Run It

Requirements:

Node.js 18 or newer
Ollama installed
Mistral pulled locally

Pull the model:

ollama pull mistral

Start Ollama:

ollama serve

Run the agent:

npm start

Ask one question:

npm start -- "Explain src/agent.js"

Inspect another project:

npm start -- --root /path/to/project "Find bugs in the main CLI file"

Run tests:

npm test

Run syntax checks:

npm run check

What to Remember

An AI agent is not just an LLM.

An AI agent is usually:

LLM + loop + tools + context + safety rules

In this project:

the CLI gets the user request
the agent loop manages steps
Ollama provides the local model
tools provide controlled abilities
safeResolve protects file access
tests protect the safety behavior

The model can request actions, but JavaScript decides what actually runs.

That is the key idea.

Final Thoughts

This project is intentionally small, but it teaches the foundation behind many larger agent systems.

Once you understand this version, you can explore more advanced ideas like:

memory across chat turns
streaming model output
richer tool schemas
patch validation
confirmation-based patch applying
MCP tools
RAG over larger codebases

But the core idea stays the same:

Mistral is a good simple default for learning, but when you are building stronger coding agents, coding-focused models usually give better results. Good options to try are qwen2.5-coder, deepseek-coder, and Gemma.

Build useful tools, keep them narrow, and let your application code enforce the safety boundaries.

SOLSTICE: Planetary Balance

Gaurav Kumar Singh — Tue, 16 Jun 2026 04:17:53 +0000

This is a submission for the June Solstice Game Jam

What I Built

Solstice Balance is an interactive 3D calibration simulator where the player stabilizes Earth's obliquity (target 23.44°) and rotational speed to prevent a simulated thermal collapse.
Players use thruster-style controls to correct tilt and spin while reacting to procedurally generated cosmic disturbances (solar flares, gravitational tides, meteors).
The goal was to make a tactile, physics-driven experience that ties to the June Solstice theme—balancing seasonal geometry with emergent hazards.

Game Demo

Play the live demo: https://solstice-game.vercel.app/
(Recommended: open in a desktop browser for best WebGL and audio support.)

solstice-game.vercel.app

Code

Full source code and development history: https://github.com/gaurav101/solstice-game

How I Built It

AI Assistance: Utilized Google Gemini to pair-program, debug complex WebGL contexts, and rapidly iterate on the core physics calculations and WebGL Sound generation.
Framework: React + TypeScript with Vite for fast iteration.
3D & Physics: Three.js for rendering and cannon-es for rigid-body physics to simulate tilt, spin, and meteor impacts.
Audio: WebAudio-based synth engine and sampled effects for real-time atmospheric feedback.
UI: Tailwind CSS for a clean, rapid HUD layout; React state syncs real-time telemetry (score, alignment, RPM) seamlessly with the WebGL loop.
Performance Optimization: Employed procedural textures, batched particle systems, and defensive resource disposal to prevent memory leaks across scene restarts. ## How to play the game Below is your official flight manual to successfully calibrate Earth's rotation and orientation, countering severe space weather, and maintaining life-supporting equilibrium.

Notable design choice: The game loop runs inside a single requestAnimationFrame driven effect that cleanly tears down Three/Cannon resources when switching game states to completely avoid leaking WebGL contexts.

How To Play the Game (https://solstice-game.vercel.app/)

🛰️ 1. The Core Objective

Your active task is to guide and maintain Earth's planetary parameters in specified target alignment zones:

Target Axial Obliquity: 23.0° to 23.9° (aiming precisely for the natural June Solstice angle of 23.44°).
Target Rotational Velocity (Spin): 1.0 to 2.5 RPM (Revolutions Per Minute).
Planetary Ecosystem Integrity: Must remain above 0%. Integrity decays rapidly any second Earth remains outside optimal thresholds.

🎮 2. Control Layout

Counter-act deep space gravitational pull and harsh solar winds by applying immediate corrective torque.

Keyboard Input	Control Board Thruster	Operational Action
`W` or `▲ Up`	Pitch Forward	Tilts Earth's axis forward pointing towards the Sun
`S` or `▼ Down`	Pitch Backward	Tilts Earth's axis backward away from the Sun
`A` or `◀ Left`	Spin Faster	Speeds up the Earth's west-to-east spin velocity
`D` or `▶ Right`	Spin Slower	Applies electromagnetic dragging to slow rotation down

☀️ 3. Key Calibration Rules

📍 The Solstice sweet spot (23.44°)

When Earth is tilted at 23.44°, the North Pole is angled perfectly toward the Sun. In this position, you will see a bright circular sunlit ring over the Arctic region (the Midnight Sun) while the Antarctic Circle remains in winter shadow. This is the June Solstice Threshold.

Maintaining the axis inside the green 23.0° - 23.9° band raises your Calibration Accuracy.
Every second spent inside optimal zones awards Equilibrium Points.

🌀 The Rotational Band (1.0 to 2.5 RPM)

Static Risk (Spin below 0.3 RPM): If the Earth stops spinning, one side of the planet is cooked under permanent radiation, and the other freezes in absolute darkness. Ecosystem integrity will drop exponentially!
Erosion Risk (Spin above 3.5 RPM): Rotating too fast generates cosmic atmospheric drag that will tear away the ozone layers. Ecosystem integrity drops rapidly.

🚨 4. Galactic Disturbance Hazards

The orbital field is subject to unexpected external solar interferences that will knock you out of alignment:

Coronal Mass Ejections (Solar Flares): Strong electromagnetic storms that apply extreme pitch forces, abruptly throwing off the planetary tilt obliquity.
Atmospheric Gravitational Tides: Tidal fluctuations that can speed up or slow down Earth's spin speed.
Meteor Incursions: Direct strikes that transfer kinetic momentum, rotating or tipping Earth suddenly.

Listen for the Audio Synth’s pitch and tempo: The onboard audio system uses warning buzzers and frantic tempo modulation to signal when parameters are entering danger thresholds.

🏆 5. Tips for Pro-Commanders

Pulsed Thrusters over Static Holding: Do not hold down thruster buttons endlessly. Tap controls in short bursts to counteract drift, letting the friction settle the planet in the optimal zone.
Balance First, Tilt Second: If you are knocked completely off-course, prioritize bringing the planetary spin back into the 1.0 - 2.5 RPM band first to stop thermal decay, then nudge the obliquity to the target solstice angle.
Observe the Shaders: Watch the gorgeous daytime sunlight and glittering nightly city light shaders. If you see city light configurations rotating either too fast or not at all, immediately act!

Initialize engine calibration, steady the core, and save the Solstice!

Prize Categories

Best Google AI Usage: Google Gemini was instrumental in prototyping the initial graphics setup, debugging tricky 3D coordinate transformations, and ensuring the physics-driven gameplay integrated perfectly with React's state management.

Build a Local RAG AI App with Ollama, Mistral, and Node.js

Gaurav Kumar Singh — Sun, 14 Jun 2026 15:19:13 +0000

Most people start using Large Language Models by asking questions directly:

Question -> LLM -> Answer

This works well for general questions.

But what happens when you ask about your own documents, company policy, product FAQ, or internal notes?

The model may not know the answer. Even worse, it may guess confidently. This is called a hallucination.

That is the problem RAG solves.

In this article, we will build a simple local RAG app using Ollama, Mistral, and Node.js.

Complete code is available here:

https://github.com/gaurav101/ai-experiment/tree/main/rag

What Is RAG?

RAG stands for Retrieval-Augmented Generation.

That sounds complex, but the idea is simple:

Before asking the LLM to answer, first search your own documents and give the most useful parts to the model.

So instead of this:

User question -> LLM -> Answer

we do this:

User question
   -> Search local documents
   -> Find relevant text
   -> Send that text to the LLM
   -> Generate an answer

Think of it like an open-book exam.

The LLM is still doing the writing, but now it has the right page open before it answers.

Why RAG Matters

RAG is important because most real AI apps need private or updated information.

For example:

A chatbot that answers questions from company documents
A support assistant that reads product FAQs
A legal assistant that searches contracts
A coding assistant that understands project docs
A personal assistant that uses your own notes

Without RAG, the model only uses what it already learned during training.

With RAG, we can give the model fresh information at runtime.

This means:

No need to retrain the model
Documents can stay private
Answers are based on your data
The system is easier to update

If your refund policy changes, you update the document and rebuild the index. You do not retrain the LLM.

What We Will Build

We will build a local RAG app that can answer questions from files stored on your machine.

The app uses:

Node.js for the code
Ollama to run models locally
Mistral to generate answers
nomic-embed-text to create embeddings
A local data/docs folder for documents
A local data/index.json file as a simple vector index

The project flow is:

Documents -> Chunks -> Embeddings -> Search -> Context -> Mistral -> Answer

Do not worry if words like "embeddings" or "vector index" feel new. We will walk through them step by step.

Step 1: Install Ollama

First, install Ollama:

https://ollama.com/download

On Linux or macOS, you can also install it with:

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama:

ollama serve

Now pull the two models we need.

Mistral will generate the final answer:

ollama pull mistral

nomic-embed-text will convert text into embeddings:

ollama pull nomic-embed-text

You can test Mistral with:

ollama run mistral

Step 2: Create the Node.js Project

Create a new project:

mkdir local-rag
cd local-rag
npm init -y

Use ES modules by adding this to package.json:

{
  "type": "module"
}

Install dotenv:

npm install dotenv

In this project, we use these scripts:

{
  "scripts": {
    "index": "node src/index-docs.js",
    "ask:ollama": "node src/ask-ollama.js"
  }
}

npm run index builds the searchable document index.

npm run ask:ollama asks a question using Ollama and Mistral.

Step 3: Add Local Documents

Create a folder for your documents:

mkdir -p data/docs

Add a file:

data/docs/company-faq.txt

Example content:

Refunds are allowed within 14 days of purchase.
Enterprise customers get priority email support.
The product supports SSO on the Business and Enterprise plans.

These documents are the knowledge base for our RAG app.

Later, when the user asks a question, the app will search these files first.

Step 4: Add Configuration

Create src/config.js.

This file keeps all important settings in one place:

export const DOCS_DIR = process.env.DOCS_DIR || "data/docs";
export const INDEX_FILE = process.env.INDEX_FILE || "data/index.json";

export const OLLAMA_BASE =
  process.env.OLLAMA_BASE_URL || "http://localhost:11434";

export const OLLAMA_EMBED_ENDPOINT = "/api/embeddings";
export const OLLAMA_EMBED_MODEL = "nomic-embed-text";

export const OLLAMA_GEN_ENDPOINT = "/api/generate";
export const OLLAMA_GEN_MODEL = process.env.OLLAMA_MODEL || "mistral";

This tells the app:

Where to read documents from
Where to save the index
Which model to use for embeddings
Which model to use for answers

Step 5: Read and Split Documents

LLMs work better when we give them small, focused pieces of text.

So we split long documents into smaller parts called chunks.

export function chunkText(text, size = 900, overlap = 150) {
  const chunks = [];
  let start = 0;

  while (start < text.length) {
    const end = start + size;
    chunks.push(text.slice(start, end));
    start += size - overlap;
  }

  return chunks.map((chunk) => chunk.trim()).filter(Boolean);
}

Here:

size = 900 means each chunk is around 900 characters
overlap = 150 means the next chunk repeats 150 characters from the previous one

The overlap is useful because important meaning can sit between two chunks.

Example:

Chunk 1: characters 0 to 900
Chunk 2: characters 750 to 1650
Chunk 3: characters 1500 to 2400

Step 6: Create Embeddings

An embedding is a list of numbers that represents the meaning of text.

For example, this sentence:

The product supports SSO on Business and Enterprise plans.

is converted into a vector:

[0.12, -0.04, 0.89, ...]

The exact numbers are not important for us.

What matters is this:

Similar text gets similar embeddings.

Why Do We Need `nomic-embed-text`?

Mistral is good at generating answers, but we also need a way to search our documents by meaning.

That is what nomic-embed-text does.

It converts text into embeddings so our app can compare:

The user's question
The chunks from our documents

Without embeddings, our app would only do simple keyword matching.

For example, if the document says:

The product supports SSO on the Business and Enterprise plans.

and the user asks:

Which subscription includes single sign-on?

keyword search may miss the connection because the words are different.

But embeddings can understand that SSO and single sign-on are related.

So in this project:

nomic-embed-text is used for search
mistral is used for answering

That means a question like:

Which plans have SSO?

should be close to the document sentence:

The product supports SSO on the Business and Enterprise plans.

Here is the embedding function:

export async function embed(text) {
  const response = await fetch("http://localhost:11434/api/embeddings", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "nomic-embed-text",
      prompt: text
    })
  });

  const data = await response.json();
  return data.embedding;
}

We use this same function for both:

Document chunks
User questions

That is how we compare a question with our documents.

Step 7: Build the Index

Now we create the index.

The index is a JSON file that stores:

The document name
The chunk text
The embedding for that chunk

export async function buildIndex() {
  const docs = await readDocuments();
  const records = [];

  for (const doc of docs) {
    const chunks = chunkText(doc.text);

    for (const [i, chunk] of chunks.entries()) {
      records.push({
        id: `${doc.source}#${i}`,
        source: doc.source,
        text: chunk,
        embedding: await embed(chunk)
      });
    }
  }

  await fs.writeFile("data/index.json", JSON.stringify(records, null, 2));
  return records.length;
}

Run:

npm run index

This creates:

data/index.json

Now your documents are searchable by meaning, not just by exact words.

Step 8: Search the Best Chunks

When the user asks a question, we need to find the document chunks that are closest to that question.

To do that, we:

Convert the question into an embedding
Compare it with every saved document embedding
Sort the results
Keep the best matches

The comparison uses cosine similarity:

function cosineSimilarity(a, b) {
  let dot = 0;
  let normA = 0;
  let normB = 0;

  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }

  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

Then we search the index:

export async function search(query, limit = 4) {
  const raw = await fs.readFile("data/index.json", "utf8");
  const index = JSON.parse(raw);

  const queryEmbedding = await embed(query);

  return index
    .map((item) => ({
      ...item,
      score: cosineSimilarity(queryEmbedding, item.embedding)
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

The result is a small set of document chunks that are most likely to contain the answer.

Step 9: Give Context to Mistral

Now we have the useful document chunks.

Next, we send them to Mistral with the user's question.

The prompt looks like this:

const prompt = `
Answer using only the context below.
If the answer is missing, say you do not know.

Context:
${context}

Question:
${question}
`;

This line is very important:

Answer using only the context below.

It tells the model not to guess.

Then we call Ollama's generation API:

const resp = await fetch("http://localhost:11434/api/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "mistral",
    prompt,
    max_tokens: 512,
    temperature: 0.2
  })
});

temperature: 0.2 makes the answer more focused and less random.

Step 10: Ask a Question

Now run:

npm run ask:ollama -- "What plans support SSO?"

Example answer:

The product supports SSO on the Business and Enterprise plans.

This answer came from the local document.

Mistral did not need to already know your product FAQ. The RAG pipeline found the right context and gave it to the model.

The Full RAG Flow

Here is the complete flow again:

1. Put documents in data/docs
2. Split documents into chunks
3. Convert chunks into embeddings
4. Save embeddings in data/index.json
5. User asks a question
6. Convert the question into an embedding
7. Find the most similar chunks
8. Add those chunks to the prompt
9. Ask Mistral to answer using that context

That is RAG.

Search first. Generate second.

Why This Local Version Is Useful

This project is intentionally simple.

It uses a JSON file instead of a vector database. That makes it easier to understand what is happening.

For learning, this is perfect.

For production, you may later replace data/index.json with a vector database such as:

Chroma
Qdrant
Weaviate
pgvector

But the core idea stays the same:

Store embeddings -> Search similar chunks -> Send context to the LLM

Conclusion

RAG is one of the most useful patterns for building practical AI apps.

It helps LLMs answer using your data without retraining the model.

In this article, we built a local RAG app with:

Ollama
Mistral
Node.js
nomic-embed-text
Local documents
A JSON-based vector index

The main idea is simple:

Search your documents first, then let the LLM answer with that context.

Complete implementation:

https://github.com/gaurav101/ai-experiment/tree/main/rag

Setup references:

MCP Server and RAG: A Simple Introduction for Developers

Gaurav Kumar Singh — Fri, 12 Jun 2026 14:46:51 +0000

AI tools are becoming more useful for developers, but they still have one big problem: they do not automatically know your private files, your latest docs, your local database, or your project rules.

Two ideas help solve this:

RAG gives AI the right information before it answers.
MCP servers let AI tools safely use your local tools and data.

Together, they make AI feel less like a generic chatbot and more like a useful coding partner.

What Is RAG?

RAG means retrieval-augmented generation.

In simple words, RAG means:

A user asks a question.
Your app searches useful documents.
Your app sends the best matching text to the AI.
The AI answers using that text.

Example:

User: What is our refund policy?

RAG search finds:
"Refunds are allowed within 14 days of purchase."

AI answer:
"Your refund policy allows refunds within 14 days of purchase."

Without RAG, the AI may guess. With RAG, it can answer from your real data.

What Is an MCP Server?

MCP means Model Context Protocol.

Think of an MCP server as a small local app that gives AI tools extra abilities.

For example, an MCP server can let an AI tool:

Search your local documentation.
Read selected project files.
Query a database.
Call an internal API.
Look up company rules.

The AI does not need direct access to everything. It calls a specific tool, and you control what that tool can do.

Example MCP tool:

Tool name: search_docs
Input: "How do I reset my password?"
Output: The best matching paragraphs from your documentation.

How RAG and MCP Work Together

RAG is the search brain. MCP is the bridge.

Here is the simple flow:

Claude, Codex, or another AI tool
        |
        asks MCP tool: search_docs("refund policy")
        |
Local MCP server
        |
Searches your local RAG index
        |
Returns useful document chunks
        |
AI writes a better answer

This is powerful because the same local RAG system can work with many AI tools.

Why Developers Benefit

MCP and RAG help developers in practical ways:

Better answers: AI uses your real docs instead of guessing.
Less copy-paste: You do not need to paste long files into chat.
Private by design: Your search index can stay on your computer.
Reusable tools: Build one search_docs tool and use it in Claude, Codex, Cursor, or other MCP clients.
Project-aware AI: The assistant can understand your codebase rules, API docs, and team notes.

For example, instead of asking:

Read all these files and explain our auth flow...

You can ask:

Search the local docs and explain how login works.

The AI calls your MCP tool, gets the right context, and answers faster.

Why JavaScript Is a Great Choice

JavaScript is one of the easiest choices for building beginner-friendly MCP and RAG tools.

Here is why:

Most developers already know some JavaScript.
Node.js is simple to run locally.
AI SDKs support JavaScript well.
MCP has a JavaScript/TypeScript SDK.
You can reuse the same code in CLI tools, servers, and web apps.

A small JavaScript RAG function can look like this:

async function answerQuestion(question) {
  const chunks = await searchLocalDocs(question);
  const context = chunks.join("\n\n");

  return askAI(`
    Use this context to answer:
    ${context}

    Question:
    ${question}
  `);
}

And an MCP tool can expose that search function:

server.registerTool(
  "search_docs",
  {
    description: "Search local project documents"
  },
  async ({ question }) => {
    const results = await searchLocalDocs(question);
    return {
      content: [{ type: "text", text: results.join("\n\n") }]
    };
  }
);

You do not need to start with a complex database. Beginners can use:

Text files for documents.
JSON for a small search index.
Ollama for local embeddings.
Node.js for the MCP server.

Later, you can upgrade to SQLite, Postgres, Chroma, LanceDB, or another vector database.

A Simple Example

Imagine you have a folder like this:

docs/
  refund-policy.txt
  api-guide.md
  onboarding-notes.md

You build a JavaScript RAG app that searches those files. Then you expose it as an MCP server.

Now you can ask Codex or Claude:

Use my local docs to explain how refunds work.

The AI can call your local search tool and answer from your files.

Final Thought

RAG makes AI more accurate. MCP makes AI more connected. JavaScript makes both easier to build.

If you are a beginner, start small: search a few text files, return the best matches, and connect that search to one AI tool. Once that works, you already understand the core idea behind many real-world AI developer tools.

Build a tiny MCP server in JavaScript -Claude, Codex friendly

Gaurav Kumar Singh — Fri, 12 Jun 2026 11:07:19 +0000

TL;DR — Ship a tiny server that exposes tools to LLMs using the Model Context Protocol (MCP). This guide shows a minimal, runnable example, explains each part, and covers common pitfalls (ESM imports, transports, adapters).

Why this matters

MCP lets models call real tools (fetching data, running commands) instead of hallucinating.
It’s a great way to extend models with live data: notifications, GitHub lookups, database queries, etc.

What you'll get

A working server (index.js) exposing a single tool: get-repo-stats
Quick instructions to run locally (stdio) or remotely (HTTP)
Short adapter patterns for OpenAI (Codex/GPT), Google Gemini, and Anthropic Claude

Quick checklist

Node 18+
npm install (project already depends on @modelcontextprotocol/sdk and zod)
Add "type": "module" to package.json for ESM

Quick start (copy-paste)

1) Install deps or verify existing:

npm install

2) Run locally:

node index.js

If you see a MODULE_TYPELESS_PACKAGE_JSON warning, add "type": "module" to package.json (example below).

Minimal index.js (copy to your repo)

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

const BASE_URL = "https://api.github.com";

const server = new McpServer({ name: 'github-stats-server', version: '1.0.0' });

server.tool(
  'get-repo-stats',
  'Get star count, fork count, and open issues for a GitHub repo',
  {
    owner: z.string().describe("GitHub username or org"),
    repo: z.string().describe("Repository name"),
  },
  async ({ owner, repo }) => {
    const res = await fetch(`${BASE_URL}/repos/${owner}/${repo}`);
    if (!res.ok) {
      return { content: [{ type: 'text', text: `Could not find repo ${owner}/${repo}` }] };
    }
    const data = await res.json();
    return {
      content: [{ type: 'text', text: `${owner}/${repo} — ⭐ ${data.stargazers_count} · 🍴 ${data.forks_count} · 🐛 ${data.open_issues_count}` }]
    };
  }
);

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

Code walkthrough

McpServer: high-level API to register tools and handle protocol
server.tool(name, description, schema, handler): register callable tools. Use zod for input validation.
Handler returns a result shaped like

{ content: [ { type: 'text', text: '...' } ] }

StdioServerTransport: easiest local transport — reads/writes over stdin/stdout
Call server.connect(transport) after registering tools so the initialization advertises available tools

ESM / import gotchas

Add "type": "module" to package.json so Node treats your files as ESM and avoids MODULE_TYPELESS_PACKAGE_JSON warning.
Use package export entrypoints and include .js extension:
- Good: import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- Bad: deep imports to dist/esm/… — Node may fail to resolve or duplicate path segments.

Example package.json snippet

{
  "name": "mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.29.0",
    "zod": "^3.25"
  }
}

Transports at a glance

stdio: local adapters (Claude Desktop, local testing). Simpler to run.
StreamableHTTP: model host calls an HTTP endpoint (preferred for cloud deployments).
WebSocket: long-lived bidirectional connections for advanced flows.

how to connect an LLM

OpenAI / Codex (function-calling flow)

Add a Local MCP Server to Codex

Codex can use local MCP servers through STDIO. MCP configuration is stored in
~/.codex/config.toml by default, or in a project-level .codex/config.toml
for trusted projects.

Option 1: Add with the Codex CLI

codex mcp add my-local-git-stat-server -- node /path/to/your/project/index.js

If the server needs environment variables:

codex mcp add my-local-server --env -- node /path/to/your/project/index.js

Option 2: Add Manually in `config.toml`

Open ~/.codex/config.toml and add:

[mcp_servers.my-local-server]
command = "node"
args = ["/path/to/your/project/index.js"]

Verify the Server

Restart Codex, then check active MCP servers from the Codex TUI:

/mcp

You can also inspect available MCP commands with:

codex mcp --help

Google Gemini

If the hosting environment supports HTTP callbacks, use StreamableHTTPClientTransport. Otherwise, run a bridge process that translates Gemini function calls into MCP client calls.

Anthropic Claude

For local Claude Desktop: the desktop app can spawn your server process and use stdio. Configure the desktop app to run node /path/index.js.
For hosted Claude integrations, prefer HTTP transport.

Small adapter sketch (pseudo)

// spawn server then connect client-facing logic
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({ command: 'node', args: ['index.js'] });
await transport.start();
const client = new Client({ name: 'bridge', version: '1.0.0' });
await client.connect(transport);

// When model asks for a tool: client.callTool({ method: 'get-repo-stats', params: { owner, repo } })

Using with OpenAI (Codex / GPT function-calling)

Recommended patterns

Local/testing: use stdio transport + StdioClientTransport (spawn the server as a child process from your adapter).
Hosted: expose your MCP server with StreamableHTTPTransport and let your adapter call it via StreamableHTTPClientTransport.

Minimal adapter sketch (pseudo)

// adapter-openai.js — high level sketch
import OpenAI from 'openai'; // or your HTTP wrapper
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; // or StreamableHTTPClientTransport


// spawn local server and connect client
const transport = new StdioClientTransport({ command: 'node', args: ['index.js'] });
await transport.start();
const client = new Client({ name: 'openai-bridge', version: '1.0.0' });
await client.connect(transport);

// When a model function call arrives (pseudo):
async function handleModelFunctionCall(name, params) {
  // Map function name to your tool method (e.g., 'get-repo-stats')
  const toolResult = await client.callTool({ method: `tools/${name}`, params });
  // Convert the MCP result into the expected function-response string or JSON and return it
  return toolResult;
}

// Use your OpenAI SDK to call model and route function-calls through handleModelFunctionCall

Notes

Keep the mapping from model function names to MCP tool names explicit and documented.
Don't commit API keys — use env vars, and sanitize when spawning processes.

Using with Anthropic Claude (Claude Desktop)

Local desktop (stdio) — easiest

1. Add your server to Claude Desktop configuration (absolute path to your index.js):

{
  "mcpServers": {
    "github-stats": {
      "command": "node",
      "args": ["/absolute/path/to/index.js"]
    }
  }
}

2. Ensure your project has "type": "module" in package.json and your imports use .js extensions.

3. Start / restart Claude Desktop. The desktop app will spawn your server and talk over stdin/stdout. Ask Claude: "What are the stats for facebook/react?" and it should call the get-repo-stats tool.

Hosted Claude / remote

If your Claude hosting supports HTTP callbacks, host the MCP server behind an HTTP wrapper and use StreamableHTTPClientTransport on the model side.

Testing tips

Run the server with node --trace-warnings index.js when debugging import/ESM issues.
Use a small script that calls client.listTools() after connecting to verify the advertised tools.

Debugging checklist

ERR_MODULE_NOT_FOUND for deep path? Switch to @modelcontextprotocol/sdk/server/mcp.js imports.
MODULE_TYPELESS_PACKAGE_JSON? Add "type": "module" to package.json.
Run node --trace-warnings index.js for resolution traces.

Security & deployment (brief)

If exposing HTTP, require auth (API key, OAuth) and use TLS.
When spawning child processes, sanitize environment and avoid leaking secrets.
Limit resource usage (timeouts, concurrency) on tools that call external services.

Make it yours (next steps)

Add more tools (issues, releases, search)
Add authentication for private GitHub repos
Wrap as an npm CLI and add a config file for easy local installs

References & where to look

SDK examples: node_modules/@modelcontextprotocol/sdk/dist/esm/examples
Official docs: https://modelcontextprotocol.io
example code : https://github.com/gaurav101/ai-experiment

[Boost]

Gaurav Kumar Singh — Tue, 02 Jun 2026 14:46:00 +0000

Gaurav Kumar Singh

Jun 2

Architectural Mastery in Node.js: Designing a Robust, Multi-Platform NPM Package

#node #typescript #designpatterns #architecture

8 min read