# 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):
```json
{
"mcpServers": {
"codebase-insights": {
"command": "uv",
"args": ["run", "codebase-insights-mcp"],
"env": {
"BITBUCKET_EMAIL": "your-email@example.com",
"BITBUCKET_API_TOKEN": "your-token",
"output_directory": "."
}
}
}
}
````
#### HTTP transport (development/testing):
```json
{
"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
```
> **Implementation Note:**
> Your server should auto-detect the transport mode and adjust logging, error handling, and environment initialization accordingly. Always validate all required environment variables before starting.
### Environment Variables
* `BITBUCKET_API_TOKEN` (required): A token with read permissions for Bitbucket repositories.
* `BITBUCKET_EMAIL` (optional): Email for Bitbucket authentication.
* `output_directory` (optional): Filesystem path for generated artifacts (default: current directory).
## Primary Goals
1. **Postman Collection Generation**: Generate Postman v2.1 collection JSON files from API codebases
2. **Product Owner Business Analysis**: Generate comprehensive business reports for non-technical stakeholders
3. **LLM-Powered Code Analysis**: Provide repository code to LLMs for intelligent analysis and insights
Users are experienced engineers familiar with API, DevOps, and automation workflows.
---
# Architecture and Design Principles
## Core Design Principles
The Context Library MCP Server follows strict clean code principles, with a clear separation of concerns:
* **Single Responsibility:** Each module and class has one clearly defined purpose.
* **Data/Logic Separation:** Pure data models are completely separate from business logic.
* **Dependency Injection:** Classes accept dependencies through their constructors, never instantiate them internally.
* **No Fallback Logic:** Fail fast. No hidden fallback or implicit retry logic.
* **Composition over Inheritance:** Use composition to add behavior and build complexity, not inheritance.
* **Immutable Data Flow:** All data models are immutable; functions/methods avoid side effects.
## Server Components
* **Framework:** FastMCP (for server/application structure)
* **Language:** Python 3.12+
* **Package Manager:** uv
* **Dependencies:** pydantic, requests, pyyaml, rich
* **Pattern:** Use singleton client patterns to avoid excessive external API calls and rate limiting.
* **Git Client:** Abstracts and manages repository cloning with authentication.
* **Analyzers:** Framework-specific code analyzers (Spring Boot, FastAPI, OpenAPI).
* **Business Analyzer:** Extracts business features and insights from code structure.
* **Report Generators:** Creates Postman collections and business reports.
* **File Operations:** All file reads/writes are performed with safety checks and path sanitization.
---
# Requirements
## Functional Requirements
### Tool 1: `generate_collection`
1. **Clone or fetch the provided repository** using authentication tokens.
2. **Analyze the codebase to discover all HTTP API endpoints** (paths, methods, schemas, auth).
* Support Python (FastAPI, Flask, Django), Node.js (Express, Nest), Java (Spring Boot).
* If an OpenAPI/Swagger spec exists, parse and use it as the canonical source.
* Otherwise, use static analysis and known patterns for inference.
3. **Generate a Postman collection (v2.1 JSON)** with all endpoints, grouped logically by resource/route.
* Include request examples, parameters, and authentication info.
* Ensure endpoints are named and documented using docstrings/comments if available.
4. **Save the generated collection** to `output_directory`, filename `{repo_name}_postman_collection.json`.
5. **Return the full path to the generated file** as the completion result.
### Tool 2: `generate_product_owner_overview`
1. **Clone repository and perform business analysis** using static code analysis.
2. **Identify business features, domains, and completion status** from code structure.
3. **Generate comprehensive Product Owner reports** in Markdown format.
4. **Save structured business data** as JSON for further analysis.
5. **Return paths to both report files**.
### Tool 3: `analyze_repository_for_llm`
1. **Clone repository and collect code files** with configurable extensions and limits.
2. **Return actual source code content** to the LLM for intelligent analysis.
3. **Provide repository structure** and metadata for context.
4. **Enable LLM-powered business logic understanding** beyond static pattern matching.
## Non-Functional Requirements
* Efficient handling of large codebases.
* All code must be readable, modular, and maintainable per clean code and architecture principles.
* Comprehensive error handling for network, parsing, and file operations—fail fast, no silent fallbacks.
* Major steps and errors must be logged with rich formatting.
* Design for extensibility—new languages/frameworks, caching layers, etc.
## Integration Points
* Use Bitbucket API for repo access.
* Integrate with FastMCP task orchestration and status reporting.
* Utilize context client for all repository/context state.
---
# Workflow Guidance
* Verify required environment variables before starting.
* Clone/fetch the Bitbucket repository, preferring manifest caching for repeated jobs.
* Detect OpenAPI/Swagger; if present, parse it.
* If no spec, analyze source using AST/static code analysis and patterns.
* Generate a well-structured Postman collection, grouping endpoints and annotating with doc/comments.
* Save safely to `output_directory` (sanitize paths) and output the final path.
* Log every significant step and any errors using `rich`.
* Structure code into modules/classes with single responsibilities, inject dependencies, and use immutable data flows.
* Use singleton pattern for any client instantiations.
* Document all functions and classes with concise docstrings.
* Annotate ambiguous endpoint logic with TODOs/comments in the collection.
* Never implement fallback logic; all critical errors should halt and be logged clearly.
---
# Acceptance Criteria
* The Postman collection is valid v2.1 and imports successfully.
* All discovered endpoints have example requests, parameters, and auth info.
* All logs/errors are clear, actionable, and formatted.
* Any missing/ambiguous endpoint logic is explicitly annotated for review.
* No mutable data structures are used for business logic; data is passed immutably.
---
# Example Usage
## Tool 1: Generate Postman Collection
**Input:**
```json
{
"repo_url": "https://bitbucket.org/myorg/myapi.git"
}
```
**Output:**
* `/output/myapi_postman_collection.json` (importable into Postman)
## Tool 2: Generate Product Owner Overview
**Input:**
```json
{
"repo_url": "https://bitbucket.org/myorg/myapi.git"
}
```
**Output:**
* `/output/myapi_product_owner_report.md` (business-focused analysis)
* `/output/myapi_business_analysis.json` (structured data)
## Tool 3: Analyze Repository for LLM
**Input:**
```json
{
"repo_url": "https://bitbucket.org/myorg/myapi.git",
"max_files": 100,
"file_extensions": [".java", ".xml", ".properties", ".yml"]
}
```
**Output:**
* Repository structure and actual source code returned to LLM for intelligent analysis
---
# Additional Guidance
* Always prefer OpenAPI if present; otherwise, maximize completeness in inferred endpoints (>80% confidence).
* Maintain clear, readable JSON; no unnecessary nesting/duplication.
* All files/paths must be sanitized and verified before writing.
* Use composition, not inheritance, for extending logic.
* No fallback/retry logic—fail and log all critical errors.
