From 30416a21411064d3aad3635e35f64dd3a94b90eb Mon Sep 17 00:00:00 2001 From: Michael Freeman Date: Sun, 26 Oct 2025 23:57:35 -0500 Subject: [PATCH] claude mcp docs --- CLAUDE_DESKTOP_SETUP.md | 168 ++++++++++++++++++++++++++++++ README.md | 29 ++++++ guided/docs/MCP_SERVER.md | 208 +++++++++++++++++++++++++++++++++++++- 3 files changed, 400 insertions(+), 5 deletions(-) create mode 100644 CLAUDE_DESKTOP_SETUP.md diff --git a/CLAUDE_DESKTOP_SETUP.md b/CLAUDE_DESKTOP_SETUP.md new file mode 100644 index 0000000..4e6dd18 --- /dev/null +++ b/CLAUDE_DESKTOP_SETUP.md @@ -0,0 +1,168 @@ +# Quick Start: Connect Claude Desktop to guided.dev + +Get AI-powered secure coding guidance in your Claude Desktop conversations. + +## Prerequisites + +- ✅ Claude Desktop installed ([download](https://claude.ai/download)) +- ✅ Node.js installed ([download](https://nodejs.org)) +- ✅ guided.dev server running + +## 1. Start the guided.dev Server + +```bash +cd /path/to/guided +mix phx.server +``` + +Verify it's running: +```bash +curl http://localhost:4000/mcp +``` + +## 2. Configure Claude Desktop + +**Find your config file:** +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Linux**: `~/.config/Claude/claude_desktop_config.json` + +**Add guided.dev to the config:** + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:4000/mcp" + ] + } + } +} +``` + +**If you have other MCP servers, just add guided.dev to the list:** + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:4000/mcp" + ] + }, + "your-other-server": { + "command": "...", + "args": ["..."] + } + } +} +``` + +## 3. Restart Claude Desktop + +Close and reopen Claude Desktop completely. + +## 4. Test It! + +In a new Claude conversation: + +``` +You: Do you have access to guided.dev? +``` + +Claude should confirm it has access to three tools: +- `tech_stack_recommendation` +- `secure_coding_pattern` +- `deployment_guidance` + +## Example Usage + +### Get Tech Stack Recommendations + +``` +You: I want to build a dashboard to track my team's metrics +``` + +Claude will use `tech_stack_recommendation` and provide secure recommendations with security advisories. + +### Get Secure Coding Patterns + +``` +You: How do I safely query a SQLite database in Python? +``` + +Claude will use `secure_coding_pattern` and show you secure code examples. + +### Get Deployment Guidance + +``` +You: Where should I deploy my Streamlit app? +``` + +Claude will use `deployment_guidance` and recommend deployment platforms. + +## Troubleshooting + +### "I don't have access to guided.dev" + +1. **Check server is running:** + ```bash + curl http://localhost:4000/mcp + ``` + +2. **Verify npx is available:** + ```bash + npx --version + ``` + +3. **Check Claude Desktop logs:** + - macOS: `~/Library/Logs/Claude/` + - Windows: `%APPDATA%\Claude\logs\` + - Linux: `~/.config/Claude/logs/` + +4. **Restart both:** + - Stop and restart guided.dev server + - Completely quit and reopen Claude Desktop + +### "Connection refused" + +Make sure Phoenix is running on port 4000: +```bash +lsof -i :4000 +``` + +Should show something like: +``` +COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME +beam.smp 1234 user 45u IPv4 0x... 0t0 TCP *:4000 (LISTEN) +``` + +### "npx: command not found" + +Install Node.js from [nodejs.org](https://nodejs.org), then try again. + +## What You Get + +When Claude uses guided.dev, it provides: + +✅ **Security-First Recommendations** - All tech stacks come with OWASP Top 10 security advisories +✅ **Secure Code Examples** - Real code snippets using best practices +✅ **Deployment Guidance** - Recommendations based on your stack and requirements +✅ **Up-to-Date Knowledge** - Curated from the guided.dev knowledge graph + +## Need More Help? + +- **Full Documentation**: [docs/MCP_SERVER.md](guided/docs/MCP_SERVER.md) +- **AGENTS.md Protocol**: [AGENTS.md](AGENTS.md) +- **GitHub Issues**: [github.com/carverauto/guided/issues](https://github.com/carverauto/guided/issues) + +--- + +**Ready to build secure software with AI?** 🚀 + +Start a conversation with Claude and ask for development guidance! diff --git a/README.md b/README.md index 0079fed..88b5f82 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,34 @@ Visit [`localhost:4000`](http://localhost:4000) from your browser. For detailed setup instructions and manual installation, see [**docs/DEVELOPMENT.md**](guided/docs/DEVELOPMENT.md). +## Using with Claude Desktop + +Connect Claude Desktop to guided.dev to get AI-powered secure coding guidance in your conversations! + +**Quick Setup:** + +1. Start the server: `mix phx.server` +2. Add to your `claude_desktop_config.json`: + ```json + { + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": ["mcp-remote", "http://localhost:4000/mcp"] + } + } + } + ``` +3. Restart Claude Desktop +4. Ask Claude: "Do you have access to guided.dev?" + +**What you get:** +- 🔒 **Security-first recommendations** with OWASP Top 10 advisories +- 💻 **Secure code patterns** with real examples +- 🚀 **Deployment guidance** for your tech stack + +**📖 Full guide:** [CLAUDE_DESKTOP_SETUP.md](CLAUDE_DESKTOP_SETUP.md) + ## Project Vision ### The Problem @@ -191,6 +219,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines. ## Documentation +- [**Claude Desktop Setup**](CLAUDE_DESKTOP_SETUP.md) - Quick start guide for Claude Desktop integration ⭐ - [Development Setup](guided/docs/DEVELOPMENT.md) - Complete setup guide - [MCP Server Guide](guided/docs/MCP_SERVER.md) - MCP server documentation and API reference - [AGENTS.md Specification](AGENTS.md) - The protocol spec for AI agents diff --git a/guided/docs/MCP_SERVER.md b/guided/docs/MCP_SERVER.md index dec8f71..cf8db4a 100644 --- a/guided/docs/MCP_SERVER.md +++ b/guided/docs/MCP_SERVER.md @@ -373,23 +373,221 @@ Guided.Graph.query(""" ### Claude Desktop Integration -To use the guided.dev MCP server with Claude Desktop: +Claude Desktop can connect to the guided.dev MCP server to provide secure coding guidance during development conversations. -1. Add to `claude_desktop_config.json`: +#### Prerequisites + +1. **Claude Desktop** installed ([download here](https://claude.ai/download)) +2. **guided.dev server running** locally: + ```bash + cd /path/to/guided + mix phx.server + ``` +3. **Node.js** installed (for `npx`) + +#### Configuration Steps + +**1. Locate your Claude Desktop config file:** + +The config file location depends on your OS: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Linux**: `~/.config/Claude/claude_desktop_config.json` + +**2. Add guided.dev to your config:** + +Since guided.dev runs as an HTTP server, use `npx mcp-remote` to connect: ```json { "mcpServers": { "guided-dev": { - "url": "http://localhost:4000/mcp" + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:4000/mcp" + ] } } } ``` -2. Restart Claude Desktop +**Full example with multiple servers:** + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:4000/mcp" + ] + }, + "github": { + "command": "/path/to/github-mcp-server", + "args": ["stdio"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here" + } + } + } +} +``` + +**3. Restart Claude Desktop** + +Close and reopen Claude Desktop to load the new configuration. + +**4. Verify the connection** + +In a new conversation with Claude, you can verify the tools are available: + +``` +You: Do you have access to guided.dev tools? +Claude: Yes, I have access to three guided.dev tools: +- tech_stack_recommendation +- secure_coding_pattern +- deployment_guidance +``` + +#### Using guided.dev with Claude + +Once configured, Claude can automatically use guided.dev during development conversations: + +**Example 1: Getting tech stack recommendations** + +``` +You: I want to build a data dashboard to track my team's metrics +Claude: [Uses tech_stack_recommendation tool] + Based on guided.dev's recommendations, I suggest using Streamlit + with SQLite for your team dashboard. However, be aware of these + security concerns: + - SQL Injection (critical): Use parameterized queries + - XSS (high): Validate and sanitize all user inputs +``` + +**Example 2: Getting secure coding patterns** + +``` +You: How do I safely query the SQLite database in my Streamlit app? +Claude: [Uses secure_coding_pattern tool for SQLite] + Here's the secure way using parameterized queries: + ```python + import sqlite3 + + # Good - Uses parameterized query + conn = sqlite3.connect('database.db') + cursor = conn.execute( + "SELECT * FROM users WHERE name = ?", + (user_input,) + ) + ``` +``` + +**Example 3: Getting deployment guidance** + +``` +You: Where should I deploy my Streamlit + SQLite app? +Claude: [Uses deployment_guidance tool] + For a Streamlit + SQLite stack, guided.dev recommends: + 1. Streamlit Cloud (free tier, low complexity, HTTPS included) + 2. Fly.io (free tier, low complexity, automatic HTTPS) +``` + +#### Troubleshooting + +**Problem**: Claude says it doesn't have access to guided.dev tools -3. The tools will be available to Claude automatically +**Solutions**: +1. Check that Phoenix server is running: `curl http://localhost:4000/mcp` +2. Verify `npx` is available: `npx --version` +3. Check Claude Desktop logs: + - **macOS**: `~/Library/Logs/Claude/` + - **Windows**: `%APPDATA%\Claude\logs\` + - **Linux**: `~/.config/Claude/logs/` +4. Ensure `mcp-remote` package is installed: `npx mcp-remote --help` + +**Problem**: Connection timeout or refused + +**Solutions**: +1. Verify server is running on correct port: + ```bash + lsof -i :4000 + ``` +2. Check firewall settings aren't blocking localhost connections +3. Try accessing directly: + ```bash + curl -X POST http://localhost:4000/mcp \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' + ``` + +**Problem**: `npx: command not found` + +**Solution**: Install Node.js from [nodejs.org](https://nodejs.org) + +#### Advanced Configuration + +**Using a different port:** + +If your Phoenix server runs on a different port, update the config: + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:4001/mcp" + ] + } + } +} +``` + +**Connecting to a remote server:** + +For production deployments: + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "https://guided.dev/mcp" + ] + } + } +} +``` + +**Adding authentication (future):** + +When authentication is added: + +```json +{ + "mcpServers": { + "guided-dev": { + "command": "npx", + "args": [ + "mcp-remote", + "https://guided.dev/mcp", + "--header", + "Authorization: Bearer ${API_KEY}" + ], + "env": { + "API_KEY": "your_api_key_here" + } + } + } +} +``` ### Custom AI Agent Integration