Metadata-Version: 2.4
Name: awesome-llm-apps-mcp
Version: 0.1.0
Summary: MCP server providing AI agent inspiration from the awesome-llm-apps collection
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# awesome-llm-apps-mcp

An MCP (Model Context Protocol) server that gives AI assistants access to **160+ AI agent examples** from the [awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps) collection.

Ask "I want to build a finance agent" and get relevant agent ideas, architecture patterns, tech stacks, and actual source code — directly inside Claude, Cursor, or any MCP-compatible tool.

## Features

- **Search agents** by keyword, use case, or technology
- **Browse categories**: Starter agents, advanced multi-agent teams, RAG, voice, MCP, and more
- **Get inspiration**: Recommended tech stacks and architecture patterns for your use case
- **Read source code**: Full Python implementations you can study and adapt
- **Zero config**: No API keys, no databases — just install and go

## Installation

```bash
pip install awesome-llm-apps-mcp
```

Or run directly with `uvx`:

```bash
uvx awesome-llm-apps-mcp
```

## Configuration

### Claude CLI

```bash
claude mcp add awesome-llm-apps -- uvx awesome-llm-apps-mcp
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "awesome-llm-apps": {
      "command": "uvx",
      "args": ["awesome-llm-apps-mcp"]
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "awesome-llm-apps": {
      "command": "uvx",
      "args": ["awesome-llm-apps-mcp"]
    }
  }
}
```

## Tools

### `search_ai_agents`

Find agents by keyword or use case. Returns lightweight summaries with relevance scores.

```
search_ai_agents("finance agent")
search_ai_agents("RAG with ChromaDB", category="rag_tutorials")
search_ai_agents("multi-agent team", limit=5)
```

### `get_agent_details`

Get full documentation, features, and tech stack for a specific agent.

```
get_agent_details("starter-ai-agents-xai-finance-agent")
```

### `get_agent_source_code`

Get the actual Python source files for an agent.

```
get_agent_source_code("starter-ai-agents-xai-finance-agent")
```

### `list_agent_categories`

Browse all categories with agent counts.

```
list_agent_categories()
```

**Categories:**
- `starter_ai_agents` — Single-agent apps with focused functionality
- `advanced_ai_agents` — Multi-agent systems and complex applications
- `rag_tutorials` — Retrieval-Augmented Generation implementations
- `advanced_llm_apps` — Advanced LLM application patterns
- `ai_agent_framework_crash_course` — Framework tutorials (Google ADK, OpenAI SDK)
- `awesome_agent_skills` — Reusable agent skill definitions
- `mcp_ai_agents` — Model Context Protocol agent implementations
- `voice_ai_agents` — Voice/audio-based agent applications

### `get_agent_inspiration`

Get high-level suggestions for a use case, including recommended tech stack and architecture.

```
get_agent_inspiration("a customer support chatbot with RAG")
```

## Development

```bash
git clone <repo>
cd agent-mcp
pip install -e ".[dev]"
pytest tests/
```

### Rebuilding the catalog

If you want to rebuild `catalog.json` from a local copy of `awesome-llm-apps`:

```bash
python scripts/build_catalog.py /path/to/awesome-llm-apps
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector awesome-llm-apps-mcp
```

## License

MIT
