Nuanced MCP server for AI agents

The Nuanced MCP Server provides code analysis capabilities to Large Language Models through the Model Context Protocol, enabling AI assistants to explore function call graphs and analyze code relationships for more contextually aware code assistance.

Installation

Prerequisites

Python 3.x
Access to the repository you want to analyze
The nuanced library

Installation Steps

To get started with the Nuanced MCP server:

Clone the repository:

git clone https://github.com/nuanced-dev/nuanced-mcp
cd nuanced-mcp

Install the required dependencies:
```
pip install -r requirements.txt
```

Configuration

Integrating with Claude Desktop

Add the following configuration to your claude_desktop_config.json file to connect the MCP server with Claude:

{
  "mcpServers": {
    "nuanced": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/nuanced-mcp",
        "run",
        "nuanced_mcp_server.py"
      ]
    }
  }
}

Make sure to replace /path/to/nuanced-mcp with the actual path to where you installed the server.

Using the MCP Server

Available Tools

The server provides several tools to analyze code structure:

Initialize a Repository

To begin analysis, initialize a code graph for a specific repository:

# Initialize graph for a repository
initialize_graph(repo_path="/path/to/your/repository")

Switch Between Repositories

Switch to a different repository that has already been initialized:

switch_repository(repo_path="/path/to/another/repository")

List All Repositories

View all repositories that have been initialized:

list_repositories()

Analyze Function Call Graphs

Get a visual representation of how functions call each other:

get_function_call_graph(
    file_path="src/example.py",
    function_name="main_function"
)

Find Dependencies

Analyze dependencies between modules or files:

# For a specific file
analyze_dependencies(file_path="src/module.py")

# For a specific module
analyze_dependencies(module_name="mypackage.submodule")

Assess Change Impact

Determine what would be affected by changing a particular function:

analyze_change_impact(
    file_path="src/core.py",
    function_name="process_data"
)

Accessing Resources

The server provides several resource endpoints for retrieving information:

Get a summary of the current code graph:
```
graph://summary
```
Get details about a specific repository:
```
graph://repo/path/to/repo/summary
```
Get detailed information about a specific function:
```
graph://function/src/file.py/function_name
```

Using Prompts

The server includes specialized prompts for common analysis tasks:

Function analysis with call graph:

analyze_function(
    file_path="src/main.py",
    function_name="initialize_app"
)

Function change impact analysis:

impact_analysis(
    file_path="src/utils.py",
    function_name="parse_config"
)

Dependency analysis:

analyze_dependencies_prompt(
    file_path="src/data_processor.py"
)

Typical Workflow

Initialize a repository:

initialize_graph(repo_path="/path/to/your/code")

Analyze a specific function's call graph:

get_function_call_graph(
    file_path="src/main.py",
    function_name="start_application"
)

Assess the impact of changes:

analyze_change_impact(
    file_path="src/core/utils.py",
    function_name="process_data"
)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "nuanced" '{"command":"uv","args":["--directory","/path/to/nuanced-mcp","run","nuanced_mcp_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "nuanced": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/nuanced-mcp",
                "run",
                "nuanced_mcp_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "nuanced": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/nuanced-mcp",
                "run",
                "nuanced_mcp_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect