Metadata-Version: 2.4
Name: llmscribe
Version: 1.2.0
Summary: Export a project folder into a single, LLM-ready text file — directory tree plus full file contents.
Author: Amrito Kundu
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/AMRITO-KUNDU/LLMScribe
Project-URL: Repository, https://github.com/AMRITO-KUNDU/LLMScribe
Project-URL: Issues, https://github.com/AMRITO-KUNDU/LLMScribe/issues
Keywords: cli,llm,codebase,developer-tools,context,prompt-engineering,code-export
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

# LLMScribe

Turn any local project into clean, structured context for AI agents.

---

## For AI Agents (primary)

LLMScribe provides a deterministic code-context infrastructure layer for AI agents. It is NOT an AI-powered coding/search agent.

### Installation

```bash
pip install llmscribe
```

### Running the MCP Server

```bash
llmscribe-mcp
```

### MCP Client Configurations

#### Cursor / Claude Desktop / Standard MCP Clients:

```json
{
  "mcpServers": {
    "llmscribe": {
      "command": "llmscribe-mcp"
    }
  }
}
```

#### Alternative Module Invocation:

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

---

## Tools Reference

LLMScribe MCP provides exactly 7 tools:

### 1. `project_map`
* **Purpose**: Generates directory tree structure without file contents.
* **Parameters**: `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Exploring repository structure before selecting specific files.

### 2. `project_overview`
* **Purpose**: Generates full directory structure and full contents of all supported text files.
* **Parameters**: `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Getting a complete overview of small-to-medium codebases in one call.

### 3. `search`
* **Purpose**: Keyword search across file paths and line-by-line file contents. Main discovery primitive for AI agents.
* **Parameters**: `query` (*str*), `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Locating specific symbols, function definitions, or import statements.

### 4. `read`
* **Purpose**: Retrieves full content of a single specific relative file path, with strict path traversal security checks.
* **Parameters**: `file_path` (*str*), `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Reading a specific file into context safely.

### 5. `read_many`
* **Purpose**: Retrieves full contents of multiple relative file paths in a single call, handling partial success if some paths fail.
* **Parameters**: `file_paths` (*list[str]*), `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Batch fetching multiple source files efficiently.

### 6. `project_dependencies`
* **Purpose**: Analyze file dependencies - what files this file depends on, what files depend on this file, local vs external vs unresolved.
* **Parameters**: `file_path` (*str*), `path` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Understanding dependency relationships and import graphs.

### 7. `project_diff`
* **Purpose**: Inspects Git status and unified diffs for staged, unstaged, or specific commits.
* **Parameters**: `path` (*Optional[str]*), `staged` (*bool*), `commit` (*Optional[str]*), `format` (*str* = `"markdown"`)
* **When to use**: Reviewing uncommitted edits or verifying changes.

---

## Agent Workflow

Recommended workflow sequence for AI agents:

```
project_map → search → read/read_many
```

### Example: Understand a New Repository
1. **`project_map()`**: Get the overall directory tree to understand repository architecture.
2. **`search("main")`**: Search for key entrypoints or symbol definitions.
3. **`read("src/main.py")` or `read_many(["src/main.py", "src/utils.py"])`**: Read the relevant source files.

### Example: Analyze Dependencies
1. **`search("FastAPI")`**: Find files using FastAPI.
2. **`project_dependencies("src/api/main.py")`**: Analyze dependencies for key files.
3. **`read_many()`**: Read all dependency files together.

---

## CLI Usage

The CLI provides the same core capabilities as MCP:

```bash
# Show project structure
llmscribe map

# Generate full project overview  
llmscribe overview

# Search project code
llmscribe search "authentication"

# Read specific files
llmscribe read src/auth/service.py
llmscribe read-many src/auth/service.py src/api/login.py

# Analyze dependencies
llmscribe dependencies src/auth/service.py

# Show git changes
llmscribe diff

# JSON output for scripts/AI agents
llmscribe search "auth" --json
llmscribe map --json
```

---

## JSON Mode

All tools support `format="json"` for structured, machine-readable output:

### Example JSON Response (search):

```json
{
  "ok": true,
  "tool": "search", 
  "path": "/path/to/project",
  "data": {
    "query": "authentication",
    "root_path": "/path/to/project",
    "matches": [
      {
        "file_path": "src/auth/service.py",
        "line_number": 10,
        "line_content": "from fastapi.security import OAuth2PasswordBearer",
        "match_type": "content",
        "matched_text": "auth"
      }
    ],
    "file_count": 5,
    "match_count": 12,
    "truncated": false,
    "truncation_limit": 1000
  },
  "metadata": {
    "query": "authentication",
    "file_count": 5,
    "match_count": 12,
    "truncated": false
  }
}
```

---

## Project Positioning

**LLMScribe provides clean, deterministic, structured code context. The AI agent provides the intelligence.**

- ✅ **Deterministic**: No LLM, embeddings, or AI ranking
- ✅ **Structured**: Consistent JSON output schemas
- ✅ **Agent-friendly**: Designed specifically for AI agent workflows
- ❌ **NOT** an AI coding agent
- ❌ **NOT** a semantic search engine
- ❌ **NOT** a generic Git client

---

## GitHub Repository Support

All tools can inspect remote GitHub repositories directly. Use `repo` parameter instead of `path`.

### Example:
```python
# Map a remote repo
project_map(repo="owner/repo")

# Search code in a remote repo
search(query="FastAPI", repo="owner/repo")
```

> **Note**: `path` and `repo` are mutually exclusive.

---

## Install

```bash
pip install llmscribe
```

## Version

Current version: 1.2.0

## License

Apache License 2.0

## Repository

[GitHub Repository](https://github.com/AMRITO-KUNDU/LLMScribe)

## Issues & Support

[GitHub Issues](https://github.com/AMRITO-KUNDU/LLMScribe/issues)
