Metadata-Version: 2.4
Name: tracenexus
Version: 0.1.12
Summary: A platform-agnostic MCP server for LLM observability
License-File: LICENSE.md
Author: Rajesh Sharma
Author-email: sharrajesh@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiohttp (>=3.11.18,<4.0.0)
Requires-Dist: fastmcp (>=2.3.4,<3.0.0)
Requires-Dist: langfuse (>=2.60.5,<3.0.0)
Requires-Dist: langsmith (>=0.3.42,<0.4.0)
Requires-Dist: pydantic (>=2.11.4,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: typing-extensions (>=4.13.2,<5.0.0)
Description-Content-Type: text/markdown

# TraceNexus

> **WORK IN PROGRESS**
>
> This project is under active development and should be considered experimental.

TraceNexus is an MCP (Model Context Protocol) server for LLM observability traces.
It currently supports LangSmith and Langfuse and runs both MCP transports:

- `streamable-http` for clients like Cursor
- `sse`

## Quick Start

### 1. Prerequisites

- Python 3.11+

### 2. Install

```bash
pip install --upgrade tracenexus
```

### 3. Configure

Create a `.env` file where you run `tracenexus`.

If you are running from a cloned repo, start with:

```bash
cp .env.example .env
```

Example `.env`:

```env
# LangSmith configuration (comma-separated)
LANGSMITH_API_KEYS="prod-api-key,dev-api-key"
LANGSMITH_NAMES="prod,dev"

# Langfuse configuration (comma-separated)
LANGFUSE_NAMES="dev,prod,staging,nightly,services"
LANGFUSE_PUBLIC_KEYS="pk_dev,pk_prod,pk_staging,pk_nightly,pk_services"
LANGFUSE_SECRET_KEYS="sk_dev,sk_prod,sk_staging,sk_nightly,sk_services"
LANGFUSE_HOSTS="https://cloud.langfuse.com,https://cloud.langfuse.com,https://cloud.langfuse.com,https://cloud.langfuse.com,https://cloud.langfuse.com"
```

Rules:

- Values are positional. Item `N` in each list must describe the same project.
- If multiple projects share one host, repeat that host value.
- Restart `tracenexus` after `.env` changes.

### 4. Run

```bash
tracenexus
```

Default endpoints:

- HTTP: `http://localhost:52734/mcp`
- SSE: `http://localhost:52735/sse`

### 5. Connect Your MCP Client

For Claude Code:

```bash
claude mcp add tracenexus --transport streamable-http --url http://localhost:52734/mcp
```

For Cursor:

```json
{
  "mcpServers": {
    "tracenexus": {
      "transport": "streamable-http",
      "url": "http://localhost:52734/mcp"
    }
  }
}
```

## Tool Naming

TraceNexus exposes tools in this format:

- `langsmith_<name>_get_trace`
- `langfuse_<name>_get_trace`

If a configured name contains dashes, they become underscores in tool names.

## Troubleshooting

- `404 ... not found within authorized project`: Key is valid, but mapped to the wrong project for that trace ID.
- `401 ... invalid credentials`: Key and host do not belong together.
- Tool names not updated after changing `.env`: Restart `tracenexus`.

## Contributing

Contributor/developer workflow is documented in `CONTRIBUTING.md`.

## License

This project is licensed under MIT. See `LICENSE.md`.

