codebase-insights-mcp: Instructions file for Claude Code

Context

You are an advanced coding agent operating in a Python 3.12+ environment, using the FastMCP framework for rapid MCP server development. Your package management is handled by uv. Required libraries include pydantic, requests, pyyaml, and rich.

The MCP Server you build must strictly adhere to robust architectural principles (see below), and follows a context-driven design for handling automated tasks.

Available MCP Tools

This server provides three main tools:

1. generate_collection - Generate Postman API collections from code repositories using static analysis
2. generate_product_owner_overview - Generate Product Owner business analysis reports using static analysis patterns
3. analyze_repository_for_llm - Clone repository and return actual code for LLM-powered analysis (recommended for deep business logic understanding)

Server Invocation & Client Configuration

Your MCP server must support both stdio and HTTP transports so it can be run in both production and development/testing environments.

• Production (stdio transport): The server is started via the uv runner using stdio for communication.
• Development/Testing (HTTP transport): The server is started as an HTTP server, typically at http://localhost:8000/mcp.

Example Client Configurations

Stdio transport (production):

{
  "mcpServers": {
    "codebase-insights": {
      "command": "uv",
      "args": ["run", "codebase-insights-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_API_TOKEN": "your-token",
        "output_directory": "."
      }
    }
  }
}

HTTP transport (development/testing):

{
  "mcpServers": {
    "codebase-insights": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Example of project structure in terms of files.

mcp-server/
├── mcp_server/
│   ├── __init__.py              # Package initialization and exports
│   ├── config.py                # Configuration variables (API keys)
│   ├── models/
│   │   ├── __init__.py          # Models package init
│   │   └── schemas.py           # Pydantic models 
│   ├── services/
│   │   ├── __init__.py          # Services package init
│   │   ├── service_1.py         # Service logic
│   │   
│   ├── utils/
│   │   ├── __init__.py          # Utils package init
│   │   └── logging.py           # Logging configuration
│   └── server.py                # MCP server setup and tool registration
├── main.py                      # Main entry point
├── pyproject.toml               # Python packaging configuration
├── LICENSE                      # MIT License
└── CLAUDE.md                    # Project documentation