Update pack

.github/workflows/publish-pypi-test.yml

@@ -58,7 +58,7 @@ jobs:
         working-directory: apps/aam-cli
 
       - name: Lint and test aam-cli
-        run: npx nx run-many -t lint,test -p aam-cli
+        run: npx nx run-many -t lint,test -p aam-cli --verbose
 
   # ==========================================================================
   #  BUILD & PUBLISH — Build wheels/sdists and upload to Test PyPI

README.md

@@ -148,13 +148,12 @@ aam pkg publish     # Upload to registry
 
 ## Default Skill Sources
 
-On first run or when you run `aam source enable-defaults`, AAM registers 5 curated community repositories:
+On first run or when you run `aam source enable-defaults`, AAM registers 4 curated community repositories:
 
 | Source | Repository | Path |
 |--------|------------|------|
 | `github/awesome-copilot` | [github/awesome-copilot](https://github.com/github/awesome-copilot) | `skills` |
 | `openai/skills:.curated` | [openai/skills](https://github.com/openai/skills) | `skills/.curated` |
-| `cursor/community-skills` | [cursor/community-skills](https://github.com/cursor/community-skills) | `skills` |
 | `anthropics/skills` | [anthropics/skills](https://github.com/anthropics/skills) | `skills` |
 | `microsoft/skills` | [microsoft/skills](https://github.com/microsoft/skills) | `.github/skills` |
 
@@ -168,14 +167,13 @@ flowchart LR
         direction TB
         A["github/awesome-copilot"]
         B["openai/skills"]
-        C["cursor/community-skills"]
-        D["anthropics/skills"]
-        E["microsoft/skills"]
+        C["anthropics/skills"]
+        D["microsoft/skills"]
         Custom["+ Your own<br/>aam source add &lt;url&gt;"]
     end
 
     subgraph AAM["🔧 AAM"]
-        Cache["~/.aam/sources-cache/"]
+        Cache["~/.aam/cache/git/"]
         Scan["Scan & Index"]
         Cache --> Scan
     end
@@ -188,7 +186,6 @@ flowchart LR
     B -->|clone| Cache
     C -->|clone| Cache
     D -->|clone| Cache
-    E -->|clone| Cache
     Custom -->|clone| Cache
 
     Scan -->|install| Cursor
@@ -203,12 +200,60 @@ flowchart LR
 
 ---
 
+## MCP Server
+
+AAM includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server, allowing IDE agents to interact with AAM directly — search packages, manage sources, install skills, and get recommendations without leaving the editor.
+
+```bash
+# Start read-only server (default, safe for any IDE)
+aam mcp serve
+
+# Enable write operations (install, publish, source management)
+aam mcp serve --allow-write
+```
+
+**IDE configuration (Cursor, Claude Desktop, Windsurf, VS Code):**
+
+```json
+{
+  "mcpServers": {
+    "aam": {
+      "command": "aam",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+The server exposes **29 tools** and **9 resources**:
+
+| Category | Read-only tools | Write tools (opt-in) |
+|----------|----------------|---------------------|
+| **Packages** | `search`, `list`, `info`, `validate` | `install`, `uninstall`, `publish`, `create_package` |
+| **Sources** | `source_list`, `source_scan`, `source_candidates`, `source_diff` | `source_add`, `source_remove`, `source_update` |
+| **Config** | `config_get`, `doctor`, `registry_list` | `config_set`, `registry_add`, `init` |
+| **Discovery** | `recommend_skills`, `available`, `outdated` | `upgrade`, `init_package` |
+| **Integrity** | `verify`, `diff` | — |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--transport` | `stdio` (default) or `http` |
+| `--port PORT` | HTTP port (default: `8000`, HTTP transport only) |
+| `--allow-write` | Enable write tools (install, publish, source management). Without this flag, only read-only tools are available. |
+| `--log-file PATH` | Log to file instead of stderr |
+| `--log-level` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+---
+
 ## Features
 
 - **One package, all platforms** — Write once, deploy to Cursor, Claude, GitHub Copilot, and Codex
 - **Dependency management** — Declare dependencies, AAM resolves them automatically
 - **Local & centralized registries** — Work offline or share with the community
 - **Package signing** — Sigstore (keyless) and GPG signature support
+- **MCP server** — IDE agents can use AAM tools directly via Model Context Protocol
 - **Simple CLI** — Intuitive commands: `init`, `install`, `pkg publish`, `source`
 
 ---
@@ -232,6 +277,9 @@ flowchart LR
 | `aam source` | Manage git artifact sources (add, list, update, remove) |
 | `aam registry` | Manage registries (init, add, list) |
 | `aam config` | Manage configuration |
+| `aam mcp serve` | Start MCP server for IDE agent integration |
+| `aam doctor` | Run environment diagnostics |
+| `aam convert` | Convert configs between platforms (Cursor, Copilot, Claude, Codex) |
 
 ---
 
@@ -290,8 +338,8 @@ AAM automatically deploys artifacts to the correct locations for each platform:
 | Platform | Skills | Agents | Prompts | Instructions |
 |----------|--------|--------|---------|--------------|
 | **Cursor** | `.cursor/skills/` | `.cursor/rules/` | `.cursor/prompts/` | `.cursor/rules/` |
-| **Claude** | `.claude/skills/` | `CLAUDE.md` | `.claude/prompts/` | `CLAUDE.md` |
-| **Copilot** | `.github/skills/` | `copilot-instructions.md` | `.github/prompts/` | `copilot-instructions.md` |
+| **Claude** | `.claude/skills/` | `.claude/agents/` | `.claude/prompts/` | `CLAUDE.md` |
+| **Copilot** | `.github/skills/` | `.github/agents/` | `.github/prompts/` | `.github/instructions/` |
 | **Codex** | `~/.codex/skills/` | `AGENTS.md` | `~/.codex/prompts/` | `AGENTS.md` |
 
 ---

apps/aam-cli/README.md

@@ -323,6 +323,139 @@ aam -v publish --dry-run
 
 ---
 
+## MCP Server
+
+AAM includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server that exposes AAM capabilities as tools for IDE agents. This lets AI assistants in Cursor, Claude Desktop, Windsurf, and VS Code search for packages, manage sources, install skills, and get recommendations directly.
+
+### Starting the Server
+
+```bash
+# Read-only mode (default — safe for any IDE)
+aam mcp serve
+
+# Enable write operations (install, publish, source add/remove, etc.)
+aam mcp serve --allow-write
+
+# HTTP/SSE transport instead of stdio
+aam mcp serve --transport http --port 8000
+
+# With logging
+aam mcp serve --log-file /tmp/aam-mcp.log --log-level DEBUG
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--transport` | `stdio` (default) or `http` |
+| `--port PORT` | HTTP port (default: `8000`, only for `--transport http`) |
+| `--allow-write` | Enable write tools — install, uninstall, publish, source management, config changes. **Without this flag, only read-only tools are available.** |
+| `--log-file PATH` | Log to file instead of stderr |
+| `--log-level` | `DEBUG`, `INFO` (default), `WARNING`, `ERROR` |
+
+### Safety Model
+
+By default the server starts in **read-only mode** — only 17 safe, non-destructive tools are available. When `--allow-write` is passed, 12 additional write tools are enabled (29 total), allowing the agent to install/uninstall packages, add/remove sources, modify configuration, and publish packages.
+
+### Available Tools
+
+**Read-only tools (always available):**
+
+| Tool | Description |
+|------|-------------|
+| `aam_search` | Search registries and sources for packages |
+| `aam_list` | List installed packages |
+| `aam_info` | Get detailed package metadata |
+| `aam_validate` | Validate package manifest and artifacts |
+| `aam_config_get` | Get configuration values |
+| `aam_registry_list` | List configured registries |
+| `aam_doctor` | Run environment diagnostics |
+| `aam_source_list` | List configured git sources |
+| `aam_source_scan` | Scan a source for artifacts |
+| `aam_source_candidates` | List unpackaged artifact candidates |
+| `aam_source_diff` | Preview upstream changes |
+| `aam_verify` | Verify package file integrity |
+| `aam_diff` | Show file differences in packages |
+| `aam_outdated` | Check for outdated source-installed packages |
+| `aam_available` | List all available artifacts from sources |
+| `aam_init_info` | Get client initialization information |
+| `aam_recommend_skills` | Recommend skills based on repo analysis |
+
+**Write tools (requires `--allow-write`):**
+
+| Tool | Description |
+|------|-------------|
+| `aam_install` | Install packages from registries or sources |
+| `aam_uninstall` | Uninstall packages |
+| `aam_publish` | Publish packages to registry |
+| `aam_create_package` | Create a package manifest |
+| `aam_config_set` | Set configuration values |
+| `aam_registry_add` | Add a new registry |
+| `aam_source_add` | Add a git source |
+| `aam_source_remove` | Remove a git source |
+| `aam_source_update` | Update git sources |
+| `aam_upgrade` | Upgrade outdated packages |
+| `aam_init` | Initialize client for a platform |
+| `aam_init_package` | Scaffold a new package |
+
+### MCP Resources
+
+The server also exposes 9 read-only resources for passive data access:
+
+| URI | Description |
+|-----|-------------|
+| `aam://config` | Current merged configuration |
+| `aam://packages/installed` | List of installed packages |
+| `aam://packages/{name}` | Details for a specific package |
+| `aam://registries` | Configured registries |
+| `aam://manifest` | Read `aam.yaml` from current directory |
+| `aam://sources` | List of git sources |
+| `aam://sources/{source_id}` | Source details with artifacts |
+| `aam://sources/{source_id}/candidates` | Candidate artifacts from a source |
+| `aam://init_status` | Client initialization status |
+
+### IDE Configuration
+
+**Cursor / Claude Desktop / Windsurf** (stdio):
+
+```json
+{
+  "mcpServers": {
+    "aam": {
+      "command": "aam",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+**With write access enabled:**
+
+```json
+{
+  "mcpServers": {
+    "aam": {
+      "command": "aam",
+      "args": ["mcp", "serve", "--allow-write"]
+    }
+  }
+}
+```
+
+**HTTP transport:**
+
+```json
+{
+  "mcpServers": {
+    "aam": {
+      "url": "http://localhost:8000"
+    }
+  }
+}
+```
+
+---
+
 ## Development
 
 ```bash

apps/aam-cli/pyproject.toml

@@ -42,6 +42,7 @@ dev = [
     "mypy>=1.11.0",
     "ruff>=0.6.0",
     "black>=24.0.0",
+    "types-PyYAML>=6.0.0",
 ]
 
 [project.scripts]
@@ -79,6 +80,8 @@ select = [
 ignore = [
     "E501",   # line too long (handled by formatter)
     "B008",   # do not perform function calls in argument defaults
+    "ARG001", # unused function arguments (false positives from API contracts)
+    "ARG002", # unused method arguments (false positives from @patch decorators, overrides)
 ]
 
 [tool.ruff.lint.isort]