Wednesday, May 21, 2025

Beyond Basic RAG: Building Virtual Subject Matter Experts with Advanced AI

We have spent years working with LLMs, RAG systems, and intelligent AI solutions, and one pattern has become abundantly clear: what works today won’t be enough tomorrow. When I first encountered Retrieval Augmented Generation (RAG), it felt revolutionary — finally, a way to transform static documentation into dynamic, interactive knowledge. But as with most technologies, the initial excitement eventually gave way to a recognition of its limitations.

If you’ve implemented a basic RAG system, you’ve likely experienced this evolution yourself: first the thrill of seeing AI retrieve answers from your knowledge base, then the growing frustration as you watch it struggle with complex queries, missing crucial context, and occasionally delivering misleading information with unwarranted confidence.

Let’s talk about going beyond basic RAG to create true virtual Subject Matter Experts (SMEs) — AI systems that don’t just retrieve information but understand it deeply, making them valuable across every domain of your organization.

From Static Documentation to Virtual SMEs

Despite all our digital transformation efforts, most knowledge systems remain glorified document repositories — what I like to call “brochureware” in an era where people expect Netflix-level personalization. While the internet has evolved from static pages to dynamic, personalized experiences, our approach to organizational knowledge often lags behind.

Consider the possibilities: an HR virtual SME that understands your specific policies and provides nuanced guidance on complex situations. A product management virtual SME that connects feature capabilities with customer needs and engineering constraints. An executive assistant virtual SME that manages not just calendars but understands priorities and relationships between initiatives.

The cost of not evolving isn’t just measured in frustrated users. It’s measured in millions spent on systems that deliver underwhelming results, experts drowning in repetitive questions instead of focusing on high-value work, and missed opportunities to transform knowledge management into a strategic asset.

The Limitations of Basic RAG

RAG represented a significant advance — pairing retrieval with generation to deliver answers from your knowledge base. But in practice, it has clear limitations:

It retrieves information without truly understanding the context of the query
It treats knowledge as separate islands rather than an interconnected ecosystem
It lacks awareness of user-specific details that could make answers more relevant
It can generate plausible-sounding but incorrect information

Basic RAG is essentially like having a reference librarian who knows where all the books are but hasn’t read any of them. This approach falls short when building a true virtual SME that requires deep understanding and contextual awareness.

Context-Augmented Generation: Building a True Virtual Expert

This is where Context-Augmented Generation (CAG) comes in. While basic RAG simply retrieves information and generates answers, CAG builds a comprehensive context model before generating a response.

Let me illustrate how this works. When someone asks a virtual HR SME about parental leave policies, instead of just searching for “parental leave,” CAG considers:

What is this person’s role and location?
How long have they been with the company?
What specific type of leave might they be eligible for?
What related policies might be relevant to their situation?

Another example:

When a customer asks about troubleshooting a technical issue, instead of just searching for “troubleshooting,” CAG asks:

What product or system does this user have?
When was it purchased or updated?
What related components might be affected?
What problems have been reported previously?
What solutions have already been attempted?

Notice both examples create what I call a “thought space” — a multi-dimensional understanding of the query that includes both explicit and implicit information. It’s the difference between an entry-level staff member who follows a script and a seasoned expert who draws on years of experience to understand the broader context.

This same approach applies whether you’re building a customer support SME, an engineering knowledge base, or a sales enablement tool. The impact can be dramatic — organizations implementing CAG report fewer escalations to human experts, higher first-contact resolution rates, and significantly improved satisfaction scores.

Cache Augmented Generation: The Temptation of “More is Better”

There’s another interpretation of the CAG acronym in the AI world that’s worth mentioning: Cache Augmented Generation. This approach has become increasingly popular as LLMs have dramatically expanded their context windows — Gemini now handling up to 2MB of characters and most modern LLMs processing 128K tokens or more.

I’ve watched the evolution of this approach with a mix of fascination and skepticism. The premise is seductive in its simplicity: with such expansive context windows, why not just stuff everything possibly relevant into the context and let the LLM sort it out?

It’s like saying, “I’m not sure which tool I need for this job, so I’ll just bring the entire toolbox.” I have even seen articles and videos declare that CAG has killed traditional RAG. Guess what? It doesn’t.

In my experience working with these systems, this approach comes with significant tradeoffs. Yes, modern LLMs are remarkably good at finding relevant information in large contexts (finding the needle in the haystack), but there’s a point of diminishing — and sometimes negative — returns.

Think of it as the difference between surgical precision and using a shotgun. When you flood the context with tangentially related information, several things happen:

Cost implications: You’re paying for every token in that context window — necessary or not
Noise ratio increases: The signal-to-noise ratio degrades, sometimes leading to lower quality responses
Potential for misinterpretations: More unrelated content creates more opportunities for the model to draw incorrect connections

The larger context windows do drive up costs predictably as you pay for tokens in and tokens out, but more concerning is what I’ve observed: adding more context doesn’t necessarily improve answers and can actually degrade them. The right context is as important as the amount. It’s a classic case where more isn’t always better.

That said, the expanding context windows do create fascinating opportunities. The key is finding the balance — using that expanded capacity for truly relevant context rather than indiscriminately loading information. Just because your truck has a bigger bed doesn’t mean you should fill it with rocks before every trip.

GraphRAG: Mapping the Relationships in Your Knowledge

Another challenge with basic RAG is that it treats your knowledge base as a collection of separate documents rather than an interconnected system. But in reality, your organizational knowledge is deeply connected — products link to features, policies connect to procedures, people relate to projects.

GraphRAG addresses this by organizing information as a network rather than isolated documents. When responding to queries, it can follow relationship paths to gather contextually relevant information, even when that information isn’t directly mentioned in the query.

Think of GraphRAG as creating a “relationship map” of your organizational knowledge. For example, when an engineer asks about implementing a specific feature, a virtual engineering SME using GraphRAG can identify connections to related components, recent architectural decisions, or known dependencies — connections that might not be explicitly documented in any single resource. Even here you are typically landing on the part of the graph related to the question using some sort of vector similarity search.

In an HR context, questions about compensation might link to performance review policies, benefits packages, and tax implications. In product management, a question about feature prioritization connects to customer feedback, roadmap planning, and engineering capacity.

This approach is particularly valuable for complex scenarios that span multiple domains or involve interactions between components. Rather than providing fragmented information about each part of the system, GraphRAG delivers a comprehensive picture that reflects the interconnected nature of organizational knowledge.

Fine-Tuning: Virtual SMEs That Speak Your Language

Generic AI models have impressive general knowledge but lack the specific terminology, processes, and domain expertise of your organization. Fine-tuning addresses this gap by adapting foundation models to your specific domain through specialized training.

The benefits are substantial:

Responses that precisely match your organization’s voice and specific knowledge
Faster generation of appropriate answers with less extensive prompting
Reduced costs by leveraging less expensive models that have been specialized

One common misconception I frequently encounter is that fine-tuning eliminates the need for RAG. It doesn’t. A fine-tuned model may generate better responses, but it still needs validation and grounding in your specific documentation. I’ve found that combining a fine-tuned model with RAG creates the best outcomes — the fine-tuned model generates high-quality responses, while RAG provides validation and citations to prevent hallucinations.

Fine-tuning teaches the model your language; RAG ensures it’s telling the truth in that language. This is crucial whether your virtual SME is supporting customers, assisting employees with HR questions, or helping engineers navigate complex technical decisions.

A Practical Implementation Roadmap

Implementation doesn’t require a massive one-time investment. The most effective approach is phased:

Start by enhancing your existing RAG system with better document segmentation and retrieval methods. This creates a foundation for more advanced approaches.
Implement basic GraphRAG capabilities for your most complex knowledge domains. This will demonstrate the value of relationship-based knowledge.
Introduce CAG for specific scenarios where context matters most. Look for use cases where understanding the user’s specific situation significantly improves response quality.
Begin fine-tuning efforts in high-impact areas. Use your highest-quality expert interactions as training data.
Integrate all approaches into a unified virtual SME system. Develop a tiered approach that applies the right technique to each query.

Each phase delivers measurable improvements, allowing you to demonstrate value while building toward a comprehensive solution. This iterative approach also allows for continuous learning and adjustment based on real-world feedback.

The Strategic Impact Across Your Organization

These aren’t just technical improvements — they’re strategic investments that deliver tangible business outcomes across departments:

In customer support: Substantial reductions in support escalations and higher satisfaction
In HR: More consistent policy application and reduced time spent on routine questions
In engineering: Faster knowledge transfer and preserved institutional memory
In sales: Better product knowledge and more consistent messaging

Looking further ahead, Gartner foresees the rise of more autonomous systems, predicting that by 2029, Agentic AI will handle 80% of common customer service issues without human intervention. This leap in automation is expected to drive a 30% reduction in operational costs, significantly widening the performance gap between organizations mastering advanced AI support and those lagging behind. The gap between organizations using basic automation and those leveraging advanced techniques will continue to widen, creating substantial competitive advantage for early adopters.

The Journey of Continuous Improvement

The path to advanced virtual SMEs isn’t a destination but a journey of continuous improvement. Start with retrieval, add smarter approaches iteratively, cache common answers, use feedback to sharpen responses, and keep human experts involved to maintain trust and quality.

When comparing basic RAG systems to more advanced approaches like CAG, GraphRAG, and fine-tuning, the difference is transformative. A virtual SME doesn’t just answer questions — it understands problems, navigates complex knowledge relationships, and delivers responses that feel genuinely intelligent.

The future isn’t about simply providing information — it’s about creating virtual subject matter experts that deliver brilliant, instant, and contextual knowledge across your entire organization. The question is: will your organization lead the way or get left behind?

Adopting GenAI for the Busy Executive

Slash Costs and Boost Loyalty with AI-Powered Documentation

Remember the early internet, when websites were mostly static “brochureware”? This evolved into e-commerce, though the brochureware approach proved surprisingly effective for customer support — allowing companies to put product documentation, HR manuals, and engineering notes online where people could reference them. Later, search capabilities were added, making this content more accessible, but a fundamental challenge remained: search alone couldn’t bridge the gap between complex documentation and user needs.

This limitation became increasingly apparent as documentation libraries grew. While subject matter experts (SMEs) could now share knowledge widely, users faced a new problem: navigating vast repositories of technical information. Even with search capabilities, customers and employees found themselves wading through dense, jargon-heavy documents, struggling to find precise answers to their questions. Finding that crucial piece of information felt like searching for a needle in a haystack. The result? Frustration, costly support calls, and even product returns.

But what if we could end that hunt entirely by transforming static documentation into something far more powerful — an interactive, intelligent system that acts as your company’s always-on digital expert? Instead of just pointing to documents, this system provides precise, instant answers in clear, natural language, regardless of the user’s preferred language. It can find the needle in the haystack instantly! This isn’t a distant dream; it’s achievable today through modern AI, delivering measurable ROI through reduced support costs, fewer returns, and significantly higher satisfaction among both customers and employees. The question is: how do we make this transformation from static content to dynamic expertise?

The key lies in moving beyond traditional keyword matching to truly understanding the meaning behind questions and content. While we leverage powerful AI tools called Large Language Models (LLMs) like ChatGPT, Claude, or Gemini, simply using these tools isn’t enough — they need to be enhanced with crucial context about your specific business and documentation.

When a customer asks a question, our AI system doesn’t simply pass their raw inquiry to the language model. Instead, it constructs a dynamic briefing package containing three essential components: operating parameters that define the AI’s role and tone, relevant contextual information pulled specifically for this query from your business documentation, and the customer’s original question. This complete package — the prompt — focuses the AI engine to deliver responses using only your approved information, ensuring relevant, controlled answers aligned with your company’s expertise. But to make this work effectively, we need to carefully manage how much information we feed into the AI’s “working memory” at once.

💡Prompt: A prompt is like a set of instructions or guidelines you give to an AI system — similar to how you might brief a new consultant or employee. Just as you would provide context, background information, and specific requirements to a team member, a prompt tells the AI what you want it to do and how you want it done. Think of it as setting up guardrails and expectations for the AI’s response.

The “working memory” of an AI, known as its context window, determines how much information it can process at once. Modern AI models can handle impressive amounts of text (up to 128,000 tokens) in this window, but efficiency remains crucial. The key is providing only the most relevant context for each query, as this helps maintain accuracy while keeping processing costs manageable.

💡Context Window / AI’s Working Memory: Imagine the AI’s working memory, technically called the “context window,” as its active mental scratchpad. It’s the temporary space where the AI holds all the information needed for the immediate task: your specific instructions (the prompt), and crucially, the necessary background context — often data from your documents provided to answer the question (like the relevant snippets found by a RAG system). This workspace isn’t infinite; it has a limited size measured in ‘tokens’ (roughly fractions of words). This size dictates how much information the AI can actively “think about” at once, making it vital to provide concise, relevant context to ensure the AI generates accurate responses and to manage costs, as AI systems typically charge based on the tokens processed both in and out.

This is where Text Embeddings act as our intelligent librarian’s card catalog. These embeddings create unique digital “fingerprints” that capture the core meaning of text chunks, allowing us to match similar ideas even when they’re expressed differently. For example, “graphics card help” and “video card support” would generate similar fingerprints. These fingerprints are stored in a Vector Database — think of it as a sophisticated index that organizes ideas rather than just words.

💡Text embedding: Think of text embeddings as digital fingerprints that uniquely identify your documentation’s ideas. When a customer asks “How do I fix my screen?”, the system matches this query’s fingerprint with related concept fingerprints like “display troubleshooting” or “monitor setup”. By matching these digital fingerprints rather than exact words, text embeddings help your documentation system understand the true meaning behind questions. This reduces support tickets and response times while improving customer satisfaction — like having an intelligent assistant that instantly recognizes related concepts in your documentation, regardless of how questions are phrased.

This idea index powers a process called Retrieval-Augmented Generation (RAG). When a user asks a question, RAG first creates a fingerprint for that question’s meaning. It then rapidly searches the Vector Database to find the document chunks with the most closely matching fingerprints — retrieving the most relevant snippets of your actual knowledge.

Critically, RAG then provides only this relevant, retrieved information to the LLM within a carefully crafted set of instructions called a Prompt. The prompt guides the AI, telling it to generate an answer based solely on the trusted company information provided. It’s like giving a brilliant research assistant the exact pages they need, ensuring their answer is accurate, relevant, and grounded in your reality.

Thus a RAG system:

Step 1: Convert user’s question into an embedding (digital idea finger print)
Step 2: Search the vector database to find matching document chunks (uses the idea index)
Step 3: Feed these chunks + instructions (the prompt) into the LLM ‘s context (working memory) to generate a final answer

RAG systems can be enhanced with advanced techniques. One key method, HyDE (Hypothetical Document Embeddings), improves search precision by imagining an ideal answer first, then using that answer’s fingerprint to find relevant matches. This solution-focused approach often yields better results than searching directly with the user’s question. While HyDE is just one example of these enhancements, even basic RAG implementations deliver significant business value.

So, how do these advancements translate into the business wins executives care about? Let’s break down the tangible returns you can expect from implementing AI-powered documentation:

Accuracy That Builds Trust: Customers find exact solutions at 2 AM, straight from your vetted documentation. No more waiting for support to open.
Dramatic Cost Savings: Support costs decrease as AI handles routine queries. Expect significant reduction in support tickets within 90 days.
Customer Loyalty Boost: 24/7 instant answers keep customers satisfied and loyal. Replace frustrating delays with immediate solutions.
Universal Understanding: AI adapts complex documentation for every user level, from beginners to experts, ensuring clear communication.

💡RAG / Vector Database: A super virtual librarian for your documentation. It creates unique fingerprints (embeddings) for every idea in your business documents and stores them in a specialized database. When a customer asks a question, the virtual librarian generates a similar fingerprint for their query and instantly finds matching ideas — regardless of exact wording. The system retrieves the most relevant document chunks based on meaning similarity, feeds them to an AI, and generates responses using your actual business knowledge. It’s like having a brilliant research assistant who instantly knows where to find every concept in your documentation library.

Imagine customers instantly resolving product issues or employees getting immediate clarity on HR policies, 24/7, without human intervention. This isn’t just a chatbot; it’s a virtual subject matter expert, always available, fluent in your company’s specific knowledge.

Implementing a RAG system isn’t just another AI initiative — it’s your strategic advantage in today’s knowledge-driven economy. By transforming your existing documentation into dynamic, AI-powered assets, you’ll dramatically enhance customer satisfaction while slashing operational costs. As competitors inevitably adopt these capabilities, delaying means surrendering your competitive edge. Just as the early internet transformed static brochureware into dynamic e-commerce, today’s AI can transform your documentation into a strategic asset. By acting now, you’re not just keeping pace — you’re positioning your company as a leader in AI-driven efficiency and customer satisfaction, saving money, building loyalty, and future-proofing your business. Start today, see the ROI tomorrow, and lead the future of knowledge management with confidence.

(This series will continue, exploring specific implementation strategies, comparisons like RAG vs. Conversational AI, and advanced techniques like graph-enhanced retrieval.)

Anthropic’s MCP: Set up Git MCP Agentic Tooling with Claude Desktop

In this detailed guide, I’ll walk you through setting up and using Model Context Protocol (MCP) Git integration with Claude Desktop. This tooling enables Claude to analyze and interact with your Git repositories directly, providing advanced code analysis and version control capabilities. We’ll cover everything from basic setup to advanced use cases, troubleshooting, and best practices. Let’s start by understanding what MCP is and why it’s important.

Here’s what we’ll cover in this comprehensive guide:

Background and Introduction
What is Model Context Protocol (MCP)
Core components and architecture
Roles of host and client applications
Setup and Installation
Prerequisites and system requirements
Installing uvx and dependencies
Configuration file setup
Git MCP server installation
Features and Capabilities
Available Git operations
Security considerations
Advanced configuration options
Use Cases and Applications
Code analysis and understanding
Development insights
Repository management
Documentation and knowledge management
Advanced search and analysis
Team collaboration insights
Project health metrics
Advanced Topics
Working with multiple repositories
Performance optimization
Best practices
Troubleshooting and Debugging
Common issues and solutions
Debug steps and procedures
Configuration validation

Background Information on MCP — Anthropic’s Agentic Tooling

Anthropic recently introduced the Model Context Protocol (MCP), an open-source standard that aims to revolutionize how AI assistants interact with data sources. This innovative protocol provides a unified framework, replacing previously fragmented systems. With Anthropic’s MCP, developers can efficiently expose data through servers or create AI applications that connect to these servers, significantly enhancing AI models’ ability to generate contextually relevant responses. While offering substantial benefits, the protocol has encountered scrutiny over privacy and data security concerns.

The Model Context Protocol (MCP) consists of three core components that work together seamlessly. As described in IKANGAI’s overview, servers function as data gateways, exposing resources, tools, and prompts from various sources like databases and code repositories. Clients, typically AI-powered tools, communicate with these servers to access the exposed data and functionalities. According to the MCP Quickstart guide, hosts are applications that initiate server connections, discover their capabilities, and strategically utilize them to solve user problems. The system operates through a secure protocol layer that facilitates message exchanges using JSON-RPC 2.0, as detailed in Anthropic’s introduction to MCP.

In the Model Context Protocol (MCP), the host and client serve distinct roles. According to the MCP Quickstart guide, the host application (like Claude Desktop) initiates connections to servers and discovers their capabilities to address user needs. The client operates within the host application, managing server connections and ensuring seamless access to data and functionalities (Metadocs’ overview,). Put simply, while the host orchestrates the interactions, the client handles the technical execution.

This is the 3rd article in this series. Be sure to check out Setting up Claude with Brave Search and Setting up Claude Filesystem MCP. In this article, I will also cover some of the challenges of using MCP and some common workarounds.

Check out this article on my site for better formatting.

Setting Up MCP Agentic Tooling — Git Integration

Now that we have some background on what MCP is and how it works, let’s walk through the process of setting up Git integration with Claude Desktop. This setup will allow Claude to analyze and interact with your Git repositories directly, providing powerful code analysis and version control capabilities. We’ll cover everything from basic requirements to advanced configurations.

Prerequisites

Claude Desktop installed
Git installed (git --version to verify)
Python’s uv package manager installed (recommended over pip)
Terminal/Command Prompt access

Installing uvx

% brew search uvx
% brew install uv
% uvx --version

uv-tool-uvx 0.5.5 (Homebrew 2024-11-27)

To install and use uvx, you first need to install the uv package manager. The steps are:

Install uv using Homebrew (on macOS) or your system’s package manager
Verify uv installation with uv --version
Verify uvx installation with uvx --version

Note that uvx is a tool built on top of uv, so having uv properly installed first is essential. The uv package manager is recommended over pip for its improved performance and dependency resolution.

If you encounter any issues during installation, make sure:

Your system’s package manager is up to date
You have the necessary permissions to install packages
Python is properly installed on your system

💡What is `uv`?

uv is a modern Python package and project management tool, written in Rust, designed to streamline Python development. It serves as a fast and unified alternative to various existing Python tools such as pip, pipx, pyenv, poetry, and others. One of its key features is uvx, which functions similarly to pipx.

What is uvx? uvx is a command provided by uv for running Python tools or scripts without requiring explicit installation. It creates temporary, isolated virtual environments for the execution of these tools, ensuring minimal setup and cleanup after execution. This makes it particularly useful for one-off tool usage.

Why use uv and uvx? The broader appeal of uv lies in its ability to unify multiple aspects of Python development: • Dependency Management: Handles dependencies efficiently using a fast resolver • Python Installation: Automatically installs required Python versions • Virtual Environments: Simplifies creation and management of virtual environments • Tool Management: Provides a centralized way to manage command-line tools via uv tool install or ephemeral execution via uvx

In summary, uvx is an efficient, user-friendly alternative to tools like pipx, offering speed, flexibility, and seamless integration with the broader capabilities of the uv ecosystem. We use in this article because the Anthropic’s tools are built with it.

…

Installation Steps

1. Create/Edit Configuration File

First, we need to locate or create the Claude Desktop configuration file:

For macOS:

# Configuration path
~/Library/Application Support/Claude/claude_desktop_config.json

For Windows:

# Configuration path
%APPDATA%\\Claude\\claude_desktop_config.json

2. Configure MCP Git Server

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository",
        "/path/to/your/git/repo"
      ]
    }
  }
}

Replace /path/to/your/git/repo with the actual path to the Git repository you want to analyze.

3. Install the Git MCP Server

Open your terminal and run:

# Using uv (recommended)
uv tool install mcp-server-git
uv tool update-shell

4. Verify Installation

Close and restart Claude Desktop
Test the connection with a simple query:

Could you show me the recent commits in my repository?

Features Available

The Git MCP server provides several capabilities:

View commit history
Analyze code changes
Search through repository content
Read file contents from specific commits
Compare different versions of files
View branch information

Troubleshooting

Common Issues and Solutions

Server Not Starting

Verify uv installation: uv --version
Check Git installation: git --version
Ensure repository path exists and is accessible

2. Permission Errors

Verify repository permissions
Check that the configured path is correct
Ensure you have read access to the repository

3. Configuration Not Loading

Verify JSON syntax in configuration file
Confirm configuration file location
Restart Claude Desktop after changes

Debug Steps

Check if Git is properly installed:

git --version

2. Verify repository access:

cd /path/to/your/git/repo
git status

3. Test MCP server directly:

uvx mcp-server-git --repository /path/to/your/git/repo

Additional Configuration Options

For more advanced setups, you can add additional parameters to the configuration:

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/path/to/your/git/repo",
        "--branch", "main",
        "--depth", "100"
      ]
    }
  }
}

Use Cases

I’ll walk through some powerful capabilities of the Git MCP integration with practical examples. Later we will cover some actual sessions and I can tell you where there are some pitfalls.

Code Analysis and Understanding

Code History Analysis

Can you analyze the evolution of the src/main.py file over the last 5 commits and explain what major changes were made?

Author Contributions

Who are the main contributors to the authentication module and what has each person focused on?

Impact Analysis

What files were most frequently changed in the last month? Can you identify potential hotspots in the codebase?

Development Insights

Bug Pattern Detection

Can you look through the commit history and identify patterns in bug fixes, particularly in the API endpoints?

Feature Development Tracking

Can you show me how the user authentication feature evolved from its initial implementation to now?

Code Quality Analysis

Looking at the commit history, can you identify areas where we’ve accumulated technical debt?

Repository Management

Branch Analysis

Can you analyze the current active branches and summarize what features are being worked on?

Merge History

Can you show me the merge history of the main branch for the last month and identify any problematic merges?

Release Analysis

Can you analyze our tagged releases and summarize the major changes between versions?

Documentation and Knowledge Management

Documentation Updates

Can you show me how our API documentation has evolved over time?

Change Documentation

Can you help me understand the context behind the recent changes to the payment processing module?

Best Practices Analysis

Can you analyze our commit messages and suggest improvements for our documentation practices?

Advanced Search and Analysis

Complex Code Search

Can you find all instances where we’ve modified our database schema across all branches?

Pattern Recognition

Can you identify similar code patterns across different modules in our codebase?

Security Analysis

Can you look through our commit history and identify any accidentally committed sensitive data?

Team Collaboration Insights

Work Patterns

Can you analyze commit patterns to show when our team is most active and productive?

Code Review Insights

Can you analyze our merge commit messages to identify common patterns in our code review process?

Knowledge Distribution

Can you show which team members have expertise in different parts of the codebase based on commit history?

Project Health Metrics

Codebase Growth

Can you show me how our codebase size has evolved over time and in which areas we’re growing the fastest?

Refactoring Impact

Can you analyze the impact of our recent refactoring efforts by showing before and after metrics?

Test Coverage Evolution

Can you show how our test coverage has evolved over the past six months?

Practical Tips for Advanced Usage

Combining with Other MCP Servers

Use the Filesystem MCP to analyze both code and related files
Combined with GitHub MCP for comprehensive repository analysis, there are currently some pitfalls with this.

2. Performance Optimization

Limit analysis depth for faster responses
Use specific file paths when analyzing large repositories

3. Best Practices

Regular repository cleanup for better performance
Structured commit messages for better analysis
Tag important milestones for easier historical analysis

Working with multiple git repos

Let me explain how MCP handles multiple Git repositories through configuration.

When setting up multiple Git repositories, you need to give each repository a unique identifier in your configuration. Here’s how it works:

{
  "mcpServers": {
    "git-project1": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/path/to/first/repo"
      ]
    },
    "git-project2": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/path/to/second/repo"
      ]
    },
    "git-project3": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/path/to/third/repo"
      ]
    }
  }
}

Key Points:

The identifiers (e.g., “git-project1”, “git-project2”) serve as unique names for each repository
When interacting with Claude Desktop, you can specify which repository you want to work with:

"Please analyze the commit history in my git-project1 repository" 
"Show me recent changes in git-project2"

3. You can also use descriptive names that make sense for your projects:

{   "mcpServers": {     
        "frontend-repo": { ... },     
        "backend-repo": { ... },     
        "docs-repo": { ... }   } }

Example Working Configuration:

{
  "mcpServers": {
    "main-app": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/Users/me/projects/main-application",
        "--branch", "main"
      ]
    },
    "api-service": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/Users/me/projects/api-service",
        "--branch", "develop"
      ]
    },
    "documentation": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository", "/Users/me/projects/docs",
        "--branch", "main"
      ]
    }
  }
}

Then in your interactions with Claude Desktop, you can be specific:

"Show me the recent commits in the api-service repository"
"What changes were made to the documentation repository last week?"
"Compare the test coverage between main-app and api-service"

This can get confusing if you have too many MCP server tools installed at once. I had a difficult experience getting Claude to select the correct Git repo, as it would get confused between the GitHub tool, the filesystem tools, and the Git tools. You have to be fairly specific in your prompts to get it to work when multiple tools are installed. This will get better over time, or I will get better at it. But it is not all roses and rainbows.

Debugging

When debugging issues with Claude MCP (Model Context Protocol) servers, particularly when they fail to use installed MCP servers, follow these systematic troubleshooting steps:

1. Verify Configuration

Configuration File: Check your claude_desktop_config.json file configuration. As detailed in the MCP-Windows guide, this file should contain correct paths to MCP server executables and environment variables, using double backslashes on Windows systems.
Server Command: According to the Windows setup guide, ensure proper server startup commands, especially for Node.js-based servers by specifying the full path to node.exe and the server's dist/index.js file.

2. Check Server Logs

Enable Logging: As recommended in the official debugging documentation, implement structured logging to track server operations, connection attempts, and errors.
View Logs: Monitor real-time logs on macOS using:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

I found tailing the log super helpful.

3. Use Debugging Tools

MCP Inspector: As described in developer first impressions, use the MCP Inspector for interactive debugging and resource inspection.
Claude Desktop Developer Tools: Enable Chrome DevTools through developer_settings.json to examine client-side errors and network activity.

4. Common Issues and Solutions

Connection Errors: For “Could not connect to MCP server” errors, verify system paths and ensure global package installation via npm install -g.
Windows-Specific Issues: Run Claude Desktop as administrator, enable developer mode, and verify Node.js and Python PATH variables.
NPM/NVM Issues: As documented in the GitHub issue tracker, consider using direct node commands instead of npx on Windows systems.

5. Restart and Test

After configuration changes, restart Claude Desktop. For quick server code reloading on macOS, use Command-R as noted in the MCP troubleshooting guide.

If you continue experiencing issues after following these steps, reach out through official support channels or community forums for additional assistance.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--allow-write",
        "/Users/richardhightower/src",
        "/Users/richardhightower/clients"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": [
          "-y",
          "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
          "BRAVE_API_KEY": "MY_ACTUAL_KEY"
      }
    },
    "git-markdown": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository",
        "/Users/richardhightower/src/project-markdown-creator"
      ]
    },
    "git-meeting-buddy": {
      "command": "uvx",
      "args": [
        "mcp-server-git",
        "--repository",
        "/Users/richardhightower/src/meeting_buddy/pythonProject"
      ]
    }
  }
}

Claude Desktop

Once you install and restart the Claude Desktop, you should see the following tools:

Git

git_add

Adds file contents to the staging area