Metadata-Version: 2.4
Name: argus-docs-mcp
Version: 0.2.0
Summary: MCP server for managing Argus project documentation from any AI client
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Argus Docs MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI clients to your Argus project documentation. Read, create, update, delete, and search docs directly from Claude, Cursor, Windsurf, or any MCP-compatible client.

## Features

- **Full CRUD** — create, read, update, and delete documentation pages
- **Full-text search** — search across titles and document content
- **Project scoping** — auto-scope to a default project or switch between projects
- **Category filtering** — organize docs as `documentation`, `api_reference`, `guide`, `changelog`, or `note`
- **Document hierarchy** — nest pages under parent documents
- **Markdown in/out** — write and read docs in markdown (auto-converted to rich text internally)

## Prerequisites

1. An Argus instance (self-hosted or cloud)
2. An API key with `documents` scope — create one in **Argus → Settings → API Keys**
3. Python 3.10+ or `uv`/`uvx`

## Quick Start

### Install

```bash
# With pip
pip install argus-docs-mcp

# Or with uv (recommended)
uv pip install argus-docs-mcp
```

### Configure Your AI Client

#### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "argus-docs": {
      "command": "argus-docs-mcp",
      "env": {
        "ARGUS_API_URL": "https://your-instance.com/api",
        "ARGUS_API_KEY": "argus_your_key_here",
        "ARGUS_PROJECT_ID": "your-project-slug"
      }
    }
  }
}
```

Or with `uvx` (no pre-install needed):

```json
{
  "mcpServers": {
    "argus-docs": {
      "command": "uvx",
      "args": ["argus-docs-mcp"],
      "env": {
        "ARGUS_API_URL": "https://your-instance.com/api",
        "ARGUS_API_KEY": "argus_your_key_here",
        "ARGUS_PROJECT_ID": "your-project-slug"
      }
    }
  }
}
```

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "argus-docs": {
      "command": "argus-docs-mcp",
      "env": {
        "ARGUS_API_URL": "https://your-instance.com/api",
        "ARGUS_API_KEY": "argus_your_key_here",
        "ARGUS_PROJECT_ID": "your-project-slug"
      }
    }
  }
}
```

#### Cursor / Windsurf

Add the same configuration to your editor's MCP settings file. Check your editor's documentation for the config file location.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ARGUS_API_URL` | Yes | Base URL of your Argus API (e.g. `https://your-instance.com/api`) |
| `ARGUS_API_KEY` | Yes | API key with `documents` scope |
| `ARGUS_PROJECT_ID` | No | Default project UUID, slug, or name. When set, tools auto-scope to this project. |

## Available Tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all accessible projects with their IDs |
| `list_docs` | List documentation pages for a project, filtered by category |
| `read_doc` | Read a document's full content as markdown |
| `create_doc` | Create a new documentation page from markdown |
| `update_doc` | Update an existing page's title and/or content |
| `delete_doc` | Delete a documentation page permanently |
| `search_docs` | Search docs by title and content with snippets |

## Usage Examples

Once connected, you can ask your AI client things like:

- "List all the documentation pages in my project"
- "Create a new API reference doc for the `/users` endpoint"
- "Update the Getting Started guide with the new installation steps"
- "Search the docs for anything about authentication"
- "Delete the outdated deployment guide"

## Development

To run locally against a dev Argus instance:

```bash
# Clone and install in editable mode
git clone <repo-url>
cd mcp-server
uv pip install -e .

# Set environment variables
export ARGUS_API_URL=http://localhost:5050/api
export ARGUS_API_KEY=argus_your_dev_key
export ARGUS_PROJECT_ID=your-project

# Run
argus-docs-mcp
```

## Troubleshooting

**"ARGUS_API_KEY not set"** — Add the `ARGUS_API_KEY` environment variable to your MCP client config.

**"API key rejected (401)"** — Check that the key hasn't been revoked. Create a new one in Argus → Settings → API Keys.

**"API key lacks 'documents' scope (403)"** — The key needs the `documents` scope. Create a new key with the correct scope.

**"Cannot reach API"** — Verify `ARGUS_API_URL` points to your Argus instance and the server is running.
