> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# IDE Setup Guide

> This document provides setup instructions for various IDEs and AI coding assistants when working on the MCP Server with LangGraph project.

This document provides setup instructions for various IDEs and AI coding assistants when working on the MCP Server with LangGraph project.

### General Notes

**IDE-Specific Configuration Files**: As of v2.0.0, IDE-specific configuration directories (`.ai/`, `.openai/`, `.cursor/`, `.claude/`, `.vscode/`) are gitignored to prevent merge conflicts and keep the repository clean. You'll need to create these directories locally based on your preferences.

***

### Visual Studio Code

#### Recommended Extensions

Create `.vscode/extensions.json`:

```json theme={null}
{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter",
    "ms-python.isort",
    "charliermarsh.ruff",
    "ms-toolsai.jupyter",
    "redhat.vscode.yaml",
    "tamasfe.even-better-toml",
    "GitHub.copilot",
    "GitHub.copilot-chat"
  ]
}
```

#### Python Settings

Create `.vscode/settings.json`:

```json theme={null}
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length=127"],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.rulers": [127]
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    ".pytest_cache": true,
    ".mypy_cache": true,
    "htmlcov": true
  }
}
```

#### Debug Configurations

Create `.vscode/launch.json`:

```json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    },
    {
      "name": "MCP Server (stdio)",
      "type": "python",
      "request": "launch",
      "module": "mcp_server_langgraph.mcp.server_stdio",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "MCP Server (StreamableHTTP)",
      "type": "python",
      "request": "launch",
      "module": "mcp_server_langgraph.mcp.server_streamable",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "Pytest: Current File",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}", "-v"],
      "console": "integratedTerminal"
    }
  ]
}
```

#### Tasks

Create `.vscode/tasks.json`:

```json theme={null}
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Tests (Unit)",
      "type": "shell",
      "command": "pytest",
      "args": ["-m", "unit", "-v"],
      "group": "test",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "Run Tests (All)",
      "type": "shell",
      "command": "make",
      "args": ["test"],
      "group": {
        "kind": "test",
        "isDefault": true
      }
    },
    {
      "label": "Format Code",
      "type": "shell",
      "command": "make",
      "args": ["format"]
    },
    {
      "label": "Lint",
      "type": "shell",
      "command": "make",
      "args": ["lint"]
    }
  ]
}
```

***

### Claude Code / Claude Desktop

#### Configuration

Create `.claude/settings.local.json`:

```json theme={null}
{
  "output_style": "concise",
  "project_context": {
    "language": "python",
    "framework": "langgraph",
    "testing": "pytest"
  }
}
```

#### Guidance Files

The project includes comprehensive AI assistant guidance:

* **`.github/CLAUDE.md`** - Complete guide for Claude Code
* **`.github/AGENTS.md`** - Extended guide with more examples

These files are version-controlled and provide:

* Project architecture overview
* Development patterns
* Common commands
* Testing strategy
* Security requirements

***

### Cursor

#### MCP Configuration

Create `.cursor/mcp.json` (Cursor supports `${workspaceFolder}` variables):

```json theme={null}
{
  "mcpServers": {
    "langgraph-agent": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_stdio"
      ],
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      },
      "envFile": "${workspaceFolder}/.env"
    },
    "langgraph-agent-streamable": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_streamable"
      ],
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src",
        "HOST": "0.0.0.0",
        "PORT": "8000"
      },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

**Note**: The `.cursor/` directory is gitignored, so you need to create this configuration locally.

#### Settings

Cursor will use the VS Code settings above, but you can override:

Create `.cursor/settings.json`:

```json theme={null}
{
  "cursor.chat.model": "claude-sonnet-4-5-20250929",
  "cursor.tab.model": "claude-sonnet-4-5-20250929"
}
```

***

### GitHub Copilot Workspace

#### Instructions

Create `.github/copilot-instructions.md`:

```md theme={null}
## GitHub Copilot Instructions

This project uses:
- Python 3.10-3.12
- LangGraph for agent orchestration
- pytest with multiple test markers (unit, integration, property, contract)
- Black formatter (line-length=127)
- Type hints required for all public APIs

When generating code:
1. Follow Google-style docstrings
2. Use type hints
3. Add appropriate pytest markers
4. Check authorization before privileged operations
5. Add observability (tracing, metrics, logging)

See `.github/AGENTS.md` for complete guidance.
```

***

### AI Coding Assistants (.ai/)

#### General AI Tools Configuration

Create `.../../README.md`:

```md theme={null}
## AI Coding Assistant Configuration

This directory contains configuration for AI coding assistants.

### Setup

See the appropriate section in `docs/development/ide-setup.md`:
- Claude Code/Desktop
- GitHub Copilot
- Cursor
- Codeium
- Tabnine

### Guidance Files

The project provides comprehensive AI assistant guidance in version control:
- `.github/CLAUDE.md` - For Claude-based assistants
- `.github/AGENTS.md` - For all AI assistants (extended)
- `.github/copilot-instructions.md` - For GitHub Copilot

These files contain:
- Architecture overview
- Development patterns
- Code standards
- Testing strategy
- Common issues & solutions
```

Create `.ai/prompts.md` with your custom prompts for reuse.

***

### OpenAI Codex

#### Configuration

Create `.openai/code-completion-config.json`:

```json theme={null}
{
  "model": "gpt-5.1-pro",
  "temperature": 0.2,
  "max_tokens": 2048,
  "context": {
    "project_type": "python-langgraph",
    "framework": "langgraph",
    "testing": "pytest",
    "style": "black",
    "line_length": 127
  }
}
```

Create `.openai/codex-instructions.md` referencing `.github/AGENTS.md` for detailed project guidance.

***

### MCP Server Configuration

All MCP-compatible IDEs can use the MCP server configuration.

#### MCP Manifest

The project includes `.mcp/manifest.json` and `.mcp/registry.json` for MCP registry publication. These are version-controlled.

#### Client Configuration

##### Quick Setup

The project includes `.mcp.json.example` as a template. To set it up:

```bash theme={null}
## Copy the example file
cp .mcp.json.example .mcp.json

## Edit with your absolute paths
## Replace /absolute/path/to/mcp-server-langgraph with your actual project path
nano .mcp.json  # or use your preferred editor
```

**Note**: `.mcp.json` is gitignored (user-specific configuration). Each developer needs to create their own based on where they cloned the repository.

##### Manual Configuration

For Claude Desktop or other MCP clients, add to your client config:

```json theme={null}
{
  "mcpServers": {
    "langgraph-agent": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_stdio"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src"
      },
      "envFile": "/absolute/path/to/project/.env"
    },
    "langgraph-agent-streamable": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_langgraph.mcp.server_streamable"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src",
        "HOST": "0.0.0.0",
        "PORT": "8000"
      },
      "envFile": "/absolute/path/to/project/.env"
    }
  }
}
```

**Important**: Replace `/absolute/path/to/project` with your actual project directory. For example:

* Linux/macOS: `/home/username/projects/mcp-server-langgraph`
* Windows: `C:/Users/username/projects/mcp-server-langgraph`

***

### PyCharm / IntelliJ IDEA

#### Project Interpreter

1. File → Settings → Project → Python Interpreter
2. Click gear → Add → Existing Environment
3. Select `.venv/bin/python`

#### Code Style

1. File → Settings → Editor → Code Style → Python
2. Set "Hard wrap at" to 127
3. Import `pyproject.toml` settings if supported (PyCharm 2023.3+)

#### Run Configurations

Create run configurations for:

* **pytest (unit)**: Target = `tests/`, Additional args = `-m unit -v`
* **pytest (all)**: Target = `tests/`, Additional args = `-v`
* **MCP Server**: Script path = `src/mcp_server_langgraph/mcp/server_stdio.py`

#### External Tools

Add Make commands as external tools:

* File → Settings → Tools → External Tools
* Add: `make test`, `make lint`, `make format`, etc.

***

### General Best Practices

#### Virtual Environment

<Note>
  **Preferred approach**: Use `uv run` to run commands without manual activation:
</Note>

```bash theme={null}
## Preferred: No activation needed
uv run pytest -m unit -v
uv run python -m mcp_server_langgraph.mcp.server_stdio
uv run python examples/demo.py
```

**Alternative**: Activate the virtual environment manually (if running multiple commands):

```bash theme={null}
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

## Now can use bare commands
pytest -m unit -v
python -m mcp_server_langgraph.mcp.server_stdio
```

<Tip>
  **IDEs can use `.venv/bin/python` directly** without requiring manual activation. Set your IDE's Python interpreter to `.venv/bin/python` and it will use the virtual environment automatically.
</Tip>

#### Environment Variables

Copy `.env.example` to `.env` and configure:

```bash theme={null}
cp .env.example .env
## Edit .env with your API keys
```

**Never commit `.env`** - it's gitignored for security.

#### Pre-commit Hooks

Install pre-commit hooks:

```bash theme={null}
pre-commit install
```

This ensures:

* Code is formatted (black, isort)
* Linting passes (flake8)
* Security scan (bandit)
* Tests run before commit (optional)

***

### Troubleshooting

#### Import Errors

If imports fail:

1. Ensure virtual environment is activated
2. Check PYTHONPATH includes `src/`:
   ```bash theme={null}
   export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
   ```
3. Reinstall dependencies:
   ```bash theme={null}
   uv sync
   ```

#### IDE Not Finding Modules

* **VS Code**: Set `python.defaultInterpreterPath` to `.venv/bin/python`
* **PyCharm**: Configure project interpreter to `.venv/bin/python`
* **All IDEs**: Mark `src/` as sources root

#### Tests Not Running

1. Ensure pytest is installed: `uv sync`
2. Check test markers are registered: `pytest --markers`
3. Verify conftest.py is found: `pytest --collect-only`

***

### Contributing

When adding IDE configurations:

1. **Do NOT commit** user-specific settings to `.vscode/`, `.cursor/`, etc.
2. **Do commit** recommendations in this file
3. **Do add** examples for new IDE setup
4. **Do update** this guide if project structure changes

See `../../.github/CONTRIBUTING.md` for contribution guidelines.

***

### References

* **Project Documentation**: `do../../README.md`
* **AI Assistant Guidance**: `.github/CLAUDE.md`, `.github/AGENTS.md`
* **Development Guide**: `docs/development/development.md`
* **Testing Guide**: `docs/development/testing.md`

**Last Updated**: 2025-10-12