added CLAUDE.md

Author: dg

CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+`nette/mcp-inspector` is an MCP (Model Context Protocol) server for Nette application introspection. It allows AI assistants to inspect DI containers, database schemas, routing, and other Nette components.
+
+## Architecture
+
+### Core Components
+
+- **`Server`** - Main MCP server orchestrator with dual transport support (CLI/HTTP)
+- **`ServerFactory`** - Creates configured Server instances, registers toolkits
+- **`Toolkit`** - Marker interface for toolkit classes
+- **`BootstrapBridge`** - Bootstraps Nette application to access DI container
+
+### Toolkits
+
+Toolkits implement the `Toolkit` marker interface and use the factory pattern:
+
+```php
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Schema\ToolAnnotations;
+
+class MyToolkit implements Toolkit
+{
+    // Factory method - returns null if dependencies unavailable
+    public static function tryCreate(BootstrapBridge $bridge): ?self
+    {
+        try {
+            $dependency = $bridge->getContainer()->getByType(SomeService::class);
+            return new self($dependency);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    public function __construct(
+        private SomeService $service,
+    ) {
+    }
+
+    /**
+     * Tool description from PHPDoc (first line/paragraph).
+     * @param string $param Parameter description for AI
+     */
+    #[McpTool(
+        name: 'my_tool',
+        annotations: new ToolAnnotations(
+            readOnlyHint: true,     // Tool doesn't modify environment
+            idempotentHint: true,   // Same args = same result
+        ),
+    )]
+    public function myMethod(string $param): array
+    {
+        return ['result' => $this->service->process($param)];
+    }
+}
+```
+
+### Built-in Toolkits
+
+- **`DIToolkit`** - DI container introspection (services, types, autowiring)
+- **`DatabaseToolkit`** - Database schema inspection (tables, columns, relationships)
+- **`RouterToolkit`** - Routing inspection (routes, URL matching, URL generation)
+
+## MCP SDK Attributes
+
+### McpTool
+
+```php
+#[McpTool(
+    name: 'tool_name',           // Optional, defaults to method name
+    description: 'Description',  // Optional, defaults to PHPDoc
+    annotations: new ToolAnnotations(...),
+)]
+```
+
+### ToolAnnotations
+
+```php
+new ToolAnnotations(
+    title: 'Human Title',        // Human-readable title
+    readOnlyHint: true,          // Tool doesn't modify environment
+    destructiveHint: false,      // Tool doesn't destroy data
+    idempotentHint: true,        // Repeatable without side effects
+    openWorldHint: false,        // Closed domain (not web search etc.)
+)
+```
+
+### Schema (parameter validation)
+
+```php
+use Mcp\Capability\Attribute\Schema;
+
+#[McpTool(name: 'example')]
+public function example(
+    #[Schema(minLength: 1, maxLength: 100)]
+    string $name,
+
+    #[Schema(minimum: 0, maximum: 100)]
+    int $percentage,
+
+    #[Schema(enum: ['asc', 'desc'])]
+    string $order = 'asc',
+): array
+```
+
+## Coding Standards
+
+- Follow Nette coding standards
+- Use PHP 8.2+ features (readonly, enums, named arguments)
+- All tool methods must return `array`
+- Use PHPDoc for tool and parameter descriptions (SDK extracts them automatically)
+- Use `ToolAnnotations` to hint tool behavior (readOnlyHint, idempotentHint)
+
+## Adding New Toolkits
+
+1. Create class in `src/McpInspector/Toolkits/` implementing `Toolkit`
+2. Add static `tryCreate(BootstrapBridge $bridge): ?self` factory method
+3. Inject actual dependencies via constructor (not BootstrapBridge)
+4. Add methods with `#[McpTool]` attribute and `ToolAnnotations`
+5. Register in `ServerFactory::create()` using `ToolkitClass::tryCreate($bridge)`
+
+## Testing
+
+Run tests:
+```bash
+composer tester
+```
+
+Run MCP server locally:
+```bash
+php bin/mcp-inspector
+```
+
+Test in Claude Code by adding to `.mcp.json`:
+```json
+{
+    "mcpServers": {
+        "nette": {
+            "command": "php",
+            "args": ["vendor/bin/mcp-inspector"]
+        }
+    }
+}
+```