Metadata-Version: 2.5
Name: mesh-mcp
Version: 0.2.0
Summary: Cross-boundary contract blast-radius engine for LLM coding agents
Project-URL: Homepage, https://github.com/Nagachaitanya007/mesh-mcp
Project-URL: Repository, https://github.com/Nagachaitanya007/mesh-mcp
Author-email: Nagachaitanya <nagachaitanyainamdar@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api-contracts,ast,blast-radius,copilot,cursor,mcp,microservices,model-context-protocol,openapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: aws
Requires-Dist: boto3>=1.34.0; extra == 'aws'
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# mesh-mcp

[![PyPI version](https://img.shields.io/pypi/v/mesh-mcp.svg)](https://pypi.org/project/mesh-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![AWS Serverless](https://img.shields.io/badge/AWS-Lambda%20Function%20URL-orange.svg)](https://aws.amazon.com/lambda/)

**Cross-boundary API contract blast-radius engine for AI coding assistants (GitHub Copilot, Cursor, Claude Desktop, Antigravity).**

When an engineer refactors or deletes an API schema property in `order-service`, AI assistants are typically **blind** to the other 20+ microservices in the company. `mesh-mcp` eliminates polyrepo blindness by building a unified Common Dependency Graph across local directories and remote GitHub repositories, reporting exact and multi-hop breaking changes before code reaches production.

---

## ⚡ Key Capabilities

* **Multi-Microservice AST Reachability:** Uses Python AST parsing and OpenAPI 3.0/3.1 contract extraction to correlate endpoint call-sites, Pydantic model instantiations, and attribute accesses (`order.tax_amount`).
* **Multi-Hop Transitive Impact Analysis:** Traces downstream breakages across hops (e.g. `Order.tax_amount` &rarr; `billing-service/client.py` &rarr; `Invoice` &rarr; `notification-service/consumer.py`).
* **Dual-Mode Repository Scanning:** Index both local workspace directories and remote GitHub repositories in the same mesh.
* **OAuth 2.0 Device Flow:** Zero-manual-PAT setup. Authenticate against private GitHub organizations with a one-time browser verification code.
* **AWS Serverless Cloud Ready:** Deploy as a remote HTTP/JSON-RPC MCP server on **AWS Lambda Function URLs** with 100% scale-to-zero and zero idle cost.

---

## 📦 Installation

```bash
pip install mesh-mcp
```

For AWS deployment capabilities:
```bash
pip install "mesh-mcp[aws]"
```

---

## ⚙️ Configuration: `mesh.yaml`

Create a `mesh.yaml` in your workspace root specifying your microservices:

```yaml
version: "1"
workspace:
  name: "ecommerce-microservices"
  description: "Cross-repo dependency network"

settings:
  cache_dir: "E:/mesh-mcp/.cache/repos"
  github:
    auth_type: "oauth"         # "oauth" | "token" | "none"

repositories:
  # Local microservice being actively developed
  - name: "order-service"
    type: "local"
    path: "./services/order_service"
    role: "producer"

  # Composite service consuming order-service
  - name: "billing-service"
    type: "local"
    path: "./services/billing_service"
    role: "composite"

  # Remote GitHub microservice
  - name: "notification-service"
    type: "github"
    owner: "MyOrg"
    repo: "notification-service"
    branch: "main"
    role: "consumer"
```

---

## 🔌 Connecting to AI Coding Assistants

### 1. VS Code / GitHub Copilot
Add to `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "mesh-mcp": {
      "command": "python",
      "args": ["-m", "mesh_mcp.server", "."]
    }
  }
}
```

### 2. Cursor IDE
Add to `.cursor/mcp.json` (or under Cursor Settings &rarr; Features &rarr; MCP):

```json
{
  "mcpServers": {
    "mesh-mcp": {
      "command": "python",
      "args": ["-m", "mesh_mcp.server", "."]
    }
  }
}
```

### 3. Remote Cloud MCP Server (Zero Local Clones)
If your team deploys `mesh-mcp` to AWS Lambda Function URLs, you can connect Copilot or Cursor directly over HTTP without cloning other microservices:

```json
{
  "mcpServers": {
    "mesh-mcp-cloud": {
      "url": "https://<your-lambda-url>.lambda-url.us-east-1.on.aws/",
      "type": "http"
    }
  }
}
```

---

## 🛠️ Available MCP Tools

AI assistants equipped with `mesh-mcp` automatically call these tools during refactoring:

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `list_contracts` | *none* | Lists all detected OpenAPI contracts, schemas, and endpoints across all repositories. |
| `trace_contract` | `contract_name` | Traces a specific contract or schema definition location and known consumer call-sites. |
| `find_consumers` | `schema_name` | Finds all source files referencing a schema (e.g. `'Order'`) or field (e.g. `'Order.tax_amount'`). |
| `check_blast_radius` | `schema_name`, `change_description` | **Core Tool:** Performs field-level direct and transitive blast-radius analysis across all repositories. |
| `refresh_mesh` | *none* | Force-refreshes remote GitHub clones and re-indexes the graph in memory. |
| `check_auth_status` | *none* | Checks GitHub authentication status. |
| `auth_github` | *none* | Initiates OAuth 2.0 Device Flow, providing a verification code and link. |

---

## 🚀 Deploying to AWS Lambda (Serverless Cloud)

Deploy `mesh-mcp` as a hosted, scale-to-zero remote MCP endpoint:

1. Ensure AWS CLI is authenticated (`aws configure`).
2. Run the deployment script:
   ```bash
   python deploy_aws.py
   ```
3. The script packages the Linux binary wheels, creates the IAM execution role, deploys the Lambda function, and outputs your live HTTPS Function URL.

---

## 🧪 Running Tests

```bash
pytest tests/unit
```

---

## 📄 License

MIT © [Nagachaitanya](https://github.com/Nagachaitanya007)
