Updated the README files to make things cleaner - hopefully

Author: mike-parkhill

README.md

@@ -2,107 +2,161 @@
 
 [![CI](https://github.com/docknetwork/truvera-mcp-server/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/docknetwork/truvera-mcp-server/actions/workflows/ci.yml)
 
-A monorepo containing multiple Model Context Protocol (MCP) servers for Truvera API integrations.
+A monorepo containing Model Context Protocol (MCP) servers for Truvera API integrations. MCP servers let AI assistants (Claude, GitHub Copilot, etc.) call real Truvera API operations as tools.
 
-## Repository Structure
+## Available Servers
+
+| Server | Status | Description |
+|--------|--------|-------------|
+| [`apps/truvera-api`](apps/truvera-api/README.md) | ✅ Production-ready | Verifiable credentials, DIDs, presentations, schemas, profiles, AP2 mandates |
+| [`apps/wallet-server`](apps/wallet-server/README.md) | 🚧 Work in progress | Truvera Wallet SDK integration — not ready for use |
+
+## Quickstart (5 minutes)
 
-This repository uses an `apps/` directory structure to organize multiple MCP servers:
+### Prerequisites
 
+- Node.js 18+
+- Docker (recommended — builds and runs the server in a container)
+- A Truvera API key ([sign up at truvera.io](https://truvera.io))
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/docknetwork/truvera-mcp-server.git
+cd truvera-mcp-server
+npm install
 ```
-truvera-mcp-server/
-├── apps/
-│   └── truvera-api/       # Main Truvera MCP Server
-│       ├── src/           # Source code
-│       ├── tests/         # Test suites
-│       ├── scripts/       # Build scripts
-│       ├── package.json   # Dependencies
-│       ├── Dockerfile     # Container build
-│       └── README.md      # Server-specific documentation
-├── .github/
-│   └── workflows/         # CI/CD pipelines
-├── .vscode/               # VS Code configuration
-├── docker-compose.yml     # Multi-service orchestration
-└── README.md             # This file
+
+### 2. Configure environment
+
+```bash
+cp apps/truvera-api/.env.example apps/truvera-api/.env
+# Edit apps/truvera-api/.env and set your TRUVERA_API_KEY
 ```
 
-## Available MCP Servers
+### 3. Build and run with Docker (recommended)
+
+```bash
+# Build the Docker image
+npm run docker:build:api
+
+# Start the server in HTTP mode on port 3000
+npm run docker:run:api
 
-### 1. Truvera MCP Server
+# Verify it's running (should return {"status":"ok",...})
+curl http://localhost:3000/health
+```
 
-The main MCP server that exposes Truvera API functionality as MCP tools. Supports verifiable credentials, DIDs, presentations, and more.
+The server is now running and ready to connect to your AI assistant. See [Connecting to AI Assistants](#connecting-to-ai-assistants) below.
 
-**📖 [Read the full documentation](apps/truvera-api/README.md)**
+### Alternative: Run locally without Docker
 
-**Quick start:**
 ```bash
 cd apps/truvera-api
-npm install
-npm run dev
+MCP_MODE=http npm run dev    # HTTP transport (recommended)
 ```
 
-## Docker Compose
+> **Transport modes:** HTTP transport is well-tested and recommended for development and production. STDIO transport is experimental — use it only if your client requires it and you are comfortable with limited test coverage.
 
-You can run all MCP servers using Docker Compose from the root directory:
+## Connecting to AI Assistants
 
-```bash
-# Start all services
-docker-compose up -d
+Once the server is running in HTTP mode on port 3000:
+
+### Claude Desktop
 
-# View logs
-docker-compose logs -f
+Add to your Claude Desktop config:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
 
-# Stop all services
-docker-compose down
+```json
+{
+   "mcpServers": {
+      "truvera": {
+         "command": "npx",
+         "args": ["-y", "mcp-remote", "http://localhost:3000/mcp", "--insecure"]
+      }
+   }
+}
 ```
 
-## Development
+### GitHub Copilot (VS Code)
 
-### Adding a New MCP Server
+The workspace `.vscode/mcp.json` is already configured. Start the server, then in the Copilot chat pane click **Configure tools...** → **Update tools** under `truvera-mcp-service-vs-code`.
 
-1. Create a new directory under `apps/`:
-   ```bash
-   mkdir -p apps/your-new-server
-   ```
+## MCP Inspector (Shared for All Servers)
 
-2. Set up your server structure with:
-   - `package.json` - Dependencies and scripts
-   - `tsconfig.json` - TypeScript configuration
-   - `src/` - Source code
-   - `tests/` - Test suites
-   - `README.md` - Documentation
+Use MCP Inspector to debug or manually exercise tools from any MCP server in this repo (for example, `apps/truvera-api` now, and `apps/wallet-server` as it matures).
 
-3. Add build tasks to `.vscode/tasks.json`
+### 1. Start the Inspector UI
 
-4. Add CI/CD steps to `.github/workflows/ci.yml`
+```bash
+npx @modelcontextprotocol/inspector
+```
 
-5. Add service to `docker-compose.yml` if needed
+### 2. Start the MCP server you want to inspect
 
-### VS Code Configuration
+Truvera API server (HTTP mode):
 
-The workspace is configured with tasks for each MCP server:
-- `build:truvera` - Build the Truvera server
-- `dev:truvera` - Run Truvera server in development mode
+```bash
+npm run docker:run:api
+# or: cd apps/truvera-api && MCP_MODE=http npm run dev
+```
 
-Use `Ctrl+Shift+B` (or `Cmd+Shift+B` on macOS) to access build tasks.
+Wallet server (HTTP mode, work in progress):
 
-## Environment Variables
+```bash
+cd apps/wallet-server
+MCP_MODE=http npm run dev
+```
 
-Each MCP server may require different environment variables. See the individual server README files for details.
+### 3. Connect from Inspector
 
-For the Truvera server, see [apps/truvera-api/README.md](apps/truvera-api/README.md#environment-variables).
+1. Open `http://localhost:6274`
+2. Choose Streamable HTTP transport
+3. Connect to the target server endpoint:
+    - Truvera API: `http://localhost:3000/mcp`
+    - Wallet server: `http://localhost:3010/mcp` (if `MCP_PORT=3010`)
 
-## CI/CD
+If connection fails, check the target server health endpoint first (`/health`) and confirm ports/env values.
 
-This repository uses GitHub Actions for continuous integration. The workflow:
-- Builds each MCP server
-- Runs unit, integration, and e2e tests
-- Performs smoke tests
+## Repository Structure
 
-See [.github/workflows/ci.yml](.github/workflows/ci.yml) for details.
+```
+truvera-mcp-server/
+├── apps/
+│   ├── truvera-api/       # ✅ Truvera REST API MCP server (production-ready)
+│   └── wallet-server/     # 🚧 Wallet SDK MCP server (work in progress)
+├── packages/
+│   └── mcp-shared/        # Shared MCP server bootstrap utilities
+├── .vscode/               # VS Code tasks, launch configs, MCP server config
+├── docker-compose.yml     # Compose file for running the truvera-api service
+└── README.md              # This file
+```
 
-## License
+## Development Commands
 
-See individual MCP server directories for licensing information.
+Run from the repo root:
+
+```bash
+npm install                  # Install all workspace dependencies
+npm run build                # Build all packages and apps
+npm run test                 # Run all tests
+npm run docker:build:api     # Build the truvera-api Docker image
+npm run docker:run:api       # Run the truvera-api container on port 3000
+```
+
+For development server with hot-reload (HTTP transport):
+
+```bash
+MCP_MODE=http npm run dev:api
+```
+
+See [apps/truvera-api/README.md](apps/truvera-api/README.md) for full documentation including all environment variables, available tools, and testing instructions.
+
+## CI/CD
+
+GitHub Actions builds all apps, runs unit and integration tests, and performs a smoke test on every push. See [.github/workflows/ci.yml](.github/workflows/ci.yml) for details.
 
 ## Contributing
 
@@ -111,5 +165,3 @@ See individual MCP server directories for licensing information.
 3. Ensure tests pass: `npm test`
 4. Submit a pull request
 
-For server-specific contribution guidelines, see the README in each app directory.
-