Metadata-Version: 2.4
Name: langsight
Version: 0.1.0
Summary: Open-source MCP observability and security platform
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anthropic>=0.85.0
Requires-Dist: anyio>=4
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: click>=8.1
Requires-Dist: clickhouse-connect>=0.14.1
Requires-Dist: fastapi>=0.135.1
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: openai>=2.28.0
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: structlog>=24
Requires-Dist: uvicorn[standard]>=0.42.0
Description-Content-Type: text/markdown

# LangSight

**Complete observability for everything an AI agent calls — MCP servers, HTTP APIs, functions, and sub-agents — with built-in health monitoring and security scanning for MCP servers.**

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![Status: Pre-release](https://img.shields.io/badge/status-pre--release-orange)]()

Agents call three types of things: MCP servers (postgres-mcp, jira-mcp, slack-mcp), non-MCP tools (Stripe API, Sendgrid, Python functions), and sub-agents. **LangSight observes all three.** Instrument once at the agent level and you automatically capture everything the agent touched — MCP or not. MCP servers get extra depth: proactive health checks, security scanning, schema drift detection, and alerting. Non-MCP tools are observed passively — every call appears in the trace, but there is no standard protocol to ping them proactively.

---

## Why LangSight

| Problem | Without LangSight | With LangSight |
|---------|-------------------|----------------|
| What did my agent call? | No trace of which tools ran, in what order | `langsight sessions --id` shows the full call tree |
| Multi-agent handoffs | No visibility across agent boundaries | Full tree via `parent_span_id` — same model as OTEL |
| Which of 15 tools failed? | 3 days of manual log replay | Root cause in the `investigate` command |
| Tool call costs | Invisible, discovered on the invoice | Per-session cost attribution in real time |
| Tool returning stale data | Agent hallucinates; you find out from users | Schema drift alert fires in <5 minutes |
| CVE in a community MCP server | Unknown until exploited | Automated CVE scan on every check |

> [!NOTE]
> 66% of MCP servers have critical code smells and 8,000+ are exposed without authentication (Invariant Labs, 2025). LangSight is the reliability and security layer that MCP infrastructure has been missing.

---

## What LangSight can do per tool type

| Tool type | Observe calls | Health check | Security scan | Cost tracking |
|-----------|:------------:|:------------:|:-------------:|:-------------:|
| MCP servers | Yes | Yes | Yes | Yes |
| HTTP APIs (Stripe, Sendgrid, etc.) | Yes | No | No | Yes |
| Python functions | Yes | No | No | Yes |
| Sub-agents | Yes | No | No | Yes |

MCP servers receive proactive health checks and security scanning because the MCP protocol is standard and inspectable. Non-MCP tools appear in every session trace but cannot be pinged or scanned — no standard protocol exists to do so.

---

## Features

**Agent Session Tracing** *(Primary)*
- Full ordered trace for every agent session — every tool call, every handoff, every failure
- `langsight sessions` — list sessions with cost, call counts, and failure counts
- `langsight sessions --id` — drill into a single session to see the complete call tree
- Per-session cost: "$0.023 on sess-abc123 by support-agent"
- Agent reliability metrics — success rate per agent, not just per tool

**Multi-Agent Tree Tracing** *(Primary)*
- When Agent A delegates to Agent B which calls Agent C, trace the full tree
- `parent_span_id` on every span — same model as OpenTelemetry distributed tracing
- Handoff spans — explicit records of agent-to-agent delegation events
- Tree reconstruction from flat span storage via recursive parent-child query

**MCP Health Monitoring** *(Secondary, unique vs competitors)*
- Continuous availability checks (ping, tools list, optional sample invocation)
- Server state tracking: `UP → DEGRADED → DOWN → STALE`
- Schema drift detection — alerts when a tool's output format changes
- p50/p99 latency tracking per server and per tool

**Security Scanning** *(Secondary, unique vs competitors)*
- CVE database matching (NVD + GitHub Advisory + MCP-specific advisories)
- OWASP MCP Top 10 automated checks
- Tool poisoning detection — baseline hash comparison on every scan
- Auth configuration audit (unauthenticated server detection, token exposure)

**Alerting**
- Slack webhook alerts with configurable thresholds
- Generic webhook for PagerDuty, Opsgenie, and custom systems
- Alert deduplication — no alert storms during outages

**Root Cause Investigation** *(Phase 2)*
- Timeline correlation across MCP calls and agent sessions
- `langsight investigate` — narrows failures to a specific tool and time window

---

## Architecture

```
  Agent Frameworks                    ┌──────────────────────────────────┐
  (CrewAI, Pydantic AI,               │         LangSight Platform        │
   OpenAI Agents SDK, etc.)           │                                  │
         │ OTLP                       │  ┌─────────────┐ ┌────────────┐  │
         ▼                            │  │ MCP Health  │ │  Security  │  │
  ┌─────────────┐                     │  │  Checker    │ │  Scanner   │  │
  │    OTEL     │────────────────────►│  └──────┬──────┘ └─────┬──────┘  │
  │  Collector  │                     │         │               │         │
  └─────────────┘                     │         ▼               ▼         │
                                      │  ┌───────────────────────────┐   │
  MCP Servers                         │  │       ClickHouse           │   │
  ┌──────────┐                        │  │  health · traces · costs   │   │
  │ server-1 │◄──────────────────────►│  └───────────────────────────┘   │
  │ server-2 │                        │  ┌───────────────────────────┐   │
  │ server-N │                        │  │       PostgreSQL           │   │
  └──────────┘                        │  │  configs · alerts · users  │   │
                                      │  └───────────────────────────┘   │
                                      │                                  │
                                      │  ┌────────────┐ ┌─────────────┐ │
                                      │  │  FastAPI   │ │  CLI        │ │
                                      │  │  REST API  │ │  langsight  │ │
                                      │  │  (Phase 2) │ │  (Phase 1)  │ │
                                      │  └─────┬──────┘ └─────────────┘ │
                                      │        ▼                         │
                                      │  ┌───────────┐  ┌─────────────┐ │
                                      │  │ Dashboard │  │ Slack /     │ │
                                      │  │ (Phase 3) │  │ Webhook     │ │
                                      │  └───────────┘  └─────────────┘ │
                                      └──────────────────────────────────┘
```

**Storage strategy**:
- **SQLite** — local CLI mode, no Docker required
- **ClickHouse** — time-series health data, OTEL traces, cost attribution
- **PostgreSQL** — app state, MCP configs, alert rules, API keys

---

## Quick Start

### Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) package manager
- Docker (for full stack with ClickHouse + PostgreSQL)

### Install

```bash
# Install from PyPI (once released)
uv tool install langsight

# Or install from source
git clone https://github.com/sumankalyan123/langsight.git
cd langsight
uv sync
```

### Initialize

```bash
langsight init
```

LangSight auto-discovers MCP servers from Claude Desktop (`~/.config/claude/claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and VS Code (`~/.vscode/mcp.json`). It writes a `.langsight.yaml` config file you can customize.

### Trace your agent sessions

Add two lines to your agent code:

```python
from langsight.sdk import LangSightClient

client = LangSightClient(url="http://localhost:8000")
traced = client.wrap(mcp_session, server_name="postgres-mcp", agent_name="support-agent")
result = await traced.call_tool("query", {"sql": "SELECT * FROM orders"})
```

View sessions from the CLI:

```bash
langsight sessions
```

```
Agent Sessions                               last 24 hours
──────────────────────────────────────────────────────────────────────
Session          Agent              Duration   Tools   Failures   Cost
sess-f2a9b1      support-agent      1,482ms       5          1   $0.023
sess-d4c7e8      data-analyst       4,210ms      12          0   $0.089
```

### Run a health check

```bash
langsight mcp-health
```

```
MCP Server Health                                    6 servers monitored
────────────────────────────────────────────────────────────────────────
Server              Status    p99 Latency   Schema    Tools   Last Check
snowflake-mcp       ✅ UP     142ms         Stable    8       12s ago
github-mcp          ✅ UP     89ms          Stable    12      8s ago
slack-mcp           ⚠️ DEG   1,240ms       Stable    4       5s ago
jira-mcp            ❌ DOWN   —             —         —       3s ago
postgres-mcp        ✅ UP     31ms          Changed   5       15s ago
filesystem-mcp      ✅ UP     12ms          Stable    6       10s ago
```

### Run a security scan

```bash
langsight security-scan
```

```
Security Scan Results                               Scanned 6 servers
────────────────────────────────────────────────────────────────────────
CRITICAL  jira-mcp           CVE-2025-6514  Remote code execution in mcp-remote
HIGH      slack-mcp          OWASP-MCP-01   Tool description contains injection pattern
HIGH      postgres-mcp       OWASP-MCP-04   No authentication configured
```

### Start continuous monitoring

```bash
langsight monitor
```

> [!TIP]
> Add `--json` to any command for machine-readable output suitable for CI/CD pipelines. Use `--ci` on `security-scan` to exit with code `1` on CRITICAL findings.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `langsight init` | Interactive setup wizard, generates `.langsight.yaml` |
| `langsight sessions` | List recent agent sessions with cost and failure counts |
| `langsight sessions --id <id>` | Full multi-agent trace for one session *(Phase 2)* |
| `langsight mcp-health` | Health status of all configured MCP servers |
| `langsight security-scan` | CVE + OWASP MCP Top 10 security audit |
| `langsight monitor` | Start continuous background monitoring with alerts |
| `langsight costs` | Tool call cost attribution by server and agent session |
| `langsight investigate` | Root cause analysis for a specific failure *(Phase 2)* |
| `langsight config` | Manage `.langsight.yaml` — add/remove/edit servers |

All commands support `--help`, `--json`, and `--verbose`.

---

## Configuration

LangSight is configured via `.langsight.yaml` in your project root (or `~/.langsight.yaml` for global config):

```yaml
servers:
  - name: snowflake-mcp
    transport: stdio
    command: python /path/to/snowflake_mcp/server.py
    tags: [production, data]

  - name: github-mcp
    transport: sse
    url: http://localhost:8080/sse
    tags: [production, devtools]

alerts:
  slack_webhook: ${LANGSIGHT_SLACK_WEBHOOK}
  error_rate_threshold: 0.05      # 5%
  latency_spike_multiplier: 3.0   # 3x baseline
  consecutive_failures: 3

storage:
  mode: sqlite                    # sqlite | postgres+clickhouse
  sqlite_path: ~/.langsight/data.db
```

> [!IMPORTANT]
> Never commit secrets to `.langsight.yaml`. Use environment variables with the `LANGSIGHT_` prefix or your existing secret management tooling.

---

## Test MCP Servers

The `test-mcps/` directory contains two real MCP servers for local development and integration testing.

| Server | Transport | Tools |
|--------|-----------|-------|
| `postgres-mcp` | stdio | `query`, `list_tables`, `describe_table`, `get_row_count`, `get_schema_summary` |
| `s3-mcp` | stdio | `list_buckets`, `list_objects`, `get_object_metadata`, `read_object`, `put_object`, `delete_object`, `search_objects` |

### Start the test stack

```bash
# Start PostgreSQL with sample data
cd test-mcps
docker compose up -d

# Set up PostgreSQL MCP
cd postgres-mcp
cp .env.example .env
uv sync

# Set up S3 MCP
cd ../s3-mcp
cp .env.example .env   # Fill in your AWS credentials
uv sync
```

The PostgreSQL database is pre-seeded with an e-commerce schema: `customers`, `products`, `orders`, `order_items`, and `agent_conversations` — useful for testing queries, schema drift detection, and agent conversation replay.

---

## Roadmap

### Phase 1 — CLI MVP
- [ ] `langsight init` with auto-discovery
- [ ] `langsight mcp-health` — health checks for stdio, SSE, StreamableHTTP transports
- [ ] `langsight security-scan` — CVE + OWASP MCP Top 10
- [ ] `langsight monitor` — continuous monitoring with Slack/webhook alerts
- [ ] `langsight costs` — tool call cost attribution from OTEL traces
- [ ] SQLite backend (no Docker required for local use)

### Phase 2 — SDK + Agent Tracing + Investigation
- [ ] `LangSightClient` Python SDK — 2-line instrumentation for any MCP client
- [ ] `parent_span_id` on `ToolCallSpan` — multi-agent tree tracing
- [ ] `langsight sessions` — agent session list and trace drill-down
- [ ] `GET /api/agents/sessions` and `GET /api/agents/sessions/{id}` endpoints
- [ ] Agent spans (lifecycle) and Handoff spans (agent-to-agent delegation)
- [ ] Framework adapters: CrewAI, Pydantic AI, OpenAI Agents SDK
- [ ] `langsight investigate` — AI-assisted root cause attribution (Claude Agent SDK)
- [ ] ClickHouse + PostgreSQL backend for production deployments
- [ ] OTEL Collector integration for trace ingestion from agent frameworks

### Phase 3 — Dashboard
- [ ] Next.js 15 web dashboard
- [ ] Real-time health overview across all MCP servers
- [ ] Security posture timeline
- [ ] Cost attribution charts by server, tool, and agent session
- [ ] Alert management UI

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| Language | Python 3.11+ |
| CLI | Click + Rich |
| API | FastAPI (async) |
| MCP client | `mcp` Python SDK |
| OLAP storage | ClickHouse |
| Metadata DB | PostgreSQL (SQLAlchemy async) |
| Local mode | SQLite |
| Trace ingestion | OTEL Collector (contrib) |
| RCA agent | Claude Agent SDK (Phase 2) |
| Dashboard | Next.js 15 + shadcn/ui (Phase 3) |
| Package manager | uv |

---

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Type check
uv run mypy src/

# Lint and format
uv run ruff check src/ && uv run ruff format src/

# Start test infrastructure
cd test-mcps && docker compose up -d
```

> [!NOTE]
> Integration tests require `docker compose up -d` and are marked `@pytest.mark.integration`. Unit tests run without any external dependencies.

---

## Security

LangSight monitors MCP security — it must itself be secure. If you discover a vulnerability, please report it via [GitHub Security Advisories](https://github.com/sumankalyan123/langsight/security/advisories) rather than a public issue.

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
