@tryvira/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1 @@
+Apache License 2.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @tryvira/mcp
+
+An npx-ready MCP server for Vira's existing scoped authority boundary.
+
+## Run it
+
+```bash
+npx @tryvira/mcp
+```
+
+The default transport is the official MCP transport. The legacy custom transport is an
+explicit migration option only: `VIRA_MCP_PROTOCOL_MODE=legacy npx @tryvira/mcp`.
+
+The launcher reads environment variables from its parent process. It does not automatically load a
+`.env` file. For a local shell, export the variables first; for an MCP client, put them in the
+client's `env` configuration:
+
+```dotenv
+VIRA_API_URL=http://127.0.0.1:4185
+VIRA_API_KEY=vira_dev_local.local-development-only-32chars
+VIRA_MCP_AUTH_TOKEN=replace-with-a-long-random-mcp-token
+VIRA_ORGANIZATION_ID=local-org
+VIRA_PROJECT_ID=local-project
+VIRA_ENVIRONMENT_ID=local
+```
+
+For example, an MCP client configuration uses the same names:
+
+```json
+{"env":{"VIRA_API_URL":"https://api.example","VIRA_API_KEY":"<customer-api-key>","VIRA_MCP_AUTH_TOKEN":"<mcp-token>","VIRA_ORGANIZATION_ID":"<org>","VIRA_PROJECT_ID":"<project>","VIRA_ENVIRONMENT_ID":"<environment>"}}
+```
+
+The default launcher uses MCP stdio. To run the optional HTTP transport explicitly, use
+`npx @tryvira/mcp --http`; it binds to `127.0.0.1` by default and requires `Authorization: Bearer
+<VIRA_MCP_AUTH_TOKEN>`. Effectful MCP tools are denied by default. Local-only effectful
+execution requires the explicit `VIRA_MCP_ALLOW_EFFECTFUL=true` opt-in; production never
+accepts that shortcut. Set `VIRA_MCP_BIND_PUBLIC=true` only when an authenticated reverse
+proxy or equivalent network boundary is present.
+
+Effectful MCP tools remain authority-gated; the launcher does not create a second execution or telemetry path.
+
+## What a client can discover
+
+After `initialize`, call `tools/list`. Read-only tools such as `resolve_semantic` may return
+semantic candidates. Effectful tools such as `resolve_runtime`, pack installation/release
+and Strategy execution call the configured authority endpoint and can be denied by scope,
+role, release state or policy.
+
+## Minimal MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "vira": {
+      "command": "npx",
+      "args": ["-y", "@tryvira/mcp"],
+      "env": {
+        "VIRA_API_URL": "https://api.example.invalid",
+        "VIRA_API_KEY": "<customer-api-key>",
+        "VIRA_MCP_AUTH_TOKEN": "<mcp-auth-token>",
+        "VIRA_MCP_AUTHORITY_URL": "https://api.example.invalid/v1/mcp/authorize",
+        "VIRA_ORGANIZATION_ID": "<organization>",
+        "VIRA_PROJECT_ID": "<project>",
+        "VIRA_ENVIRONMENT_ID": "<environment>"
+      }
+    }
+  }
+}
+```
+
+Never paste real credentials into a checked-in client configuration. For local-only effectful
+testing, use the local stack and its documented development credentials; the production
+authority path does not accept the local bypass.
+
+See [`docs/MCP_GUIDE.md`](../../docs/MCP_GUIDE.md) for JSON-RPC discovery, tool examples and
+authority/error behavior.