@wincode/mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,58 @@
1
- # Temporary Holding Version
1
+ # `@wincode/mcp`
2
2
 
3
- 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.
3
+ `@wincode/mcp` is a Wincode-owned MCP extension package, not MCP support built into Coding-Agent. Its root export is host-agnostic MCP client/domain code; `@wincode/mcp/plugin` is the Wincode Plugin adapter and imports only the host's public Plugin contracts. This keeps the extension boundary without introducing an internal MCP registration API in Coding-Agent.
4
+
5
+ ## Owns
6
+
7
+ - MCP configuration schema, validation, and server configuration resolution.
8
+ - The public CLI-management API for listing, adding, removing, and authenticating MCP servers.
9
+ - MCP client adapters and server lifecycle, discovery, reconnection, and status.
10
+ - Collision-resistant tool dispatch identities, manifest limits, and result sanitization.
11
+ - The MCP Plugin factory, per-Turn tool registration, status panel, and `/mcps` command.
12
+
13
+ ## Configuration
14
+
15
+ General settings and MCP server definitions are separate namespaces:
16
+
17
+ - User settings: `~/.wincode/settings.json` or `settings.jsonc`.
18
+ - User MCP servers: `~/.wincode/mcp.json`.
19
+ - Trusted project MCP servers: `<project>/.wincode/mcp.json`.
20
+
21
+ `mcp.json` contains a top-level `mcpServers` object. Local entries use a command plus optional arguments, environment, and working directory. Remote entries use an absolute HTTP(S) URL and optional headers. Wincode supports stdio and Streamable HTTP; legacy SSE is not supported.
22
+
23
+ ```json
24
+ {
25
+ "mcpServers": {
26
+ "local-tools": {
27
+ "command": "bun",
28
+ "args": ["run", "./mcp-server.ts"],
29
+ "env": { "API_TOKEN": "$MCP_API_TOKEN" }
30
+ },
31
+ "remote-tools": {
32
+ "type": "http",
33
+ "url": "https://mcp.example.com/mcp",
34
+ "headers": { "Authorization": "Bearer $MCP_API_TOKEN" }
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ Shell-style `$NAME`, `${NAME}`, and `$env:NAME` references are expanded from the process environment. `$$` and `$!` escape a literal dollar sign and exclamation mark. A leading `!` in an `env` or `headers` value runs a shell command and uses its trimmed standard output; command execution is time-limited and output-bounded. Keep secret values in environment variables or Wincode's user-scoped secret storage, never in project files. MCP configuration rejects `oauth.clientSecret` at every scope; OAuth client secrets and tokens belong in the dedicated host-managed MCP secret store.
41
+
42
+ Trusted project definitions can configure local commands, remote endpoints, and headers. A project definition replaces the user definition for that server rather than inheriting its credentials. A project may overlay only `enabled`, `exposure`, and `toolExposure` on a user-defined server; it cannot apply partial overlays to Plugin-registered servers. Project MCP configuration is omitted unless the project root has been trusted. Trust is not a sandbox: trusted local MCP processes run with Wincode's operating-system privileges.
43
+
44
+ Plugin-owned MCP registrations enter the same managed catalog with Plugin provenance. File-configured servers take precedence on name conflicts, which are diagnosed.
45
+
46
+ ## Public management API
47
+
48
+ The package root exports `createMcpManagement`. Its `list`, `add`, `remove`, `login`, and `logout` operations own MCP configuration semantics, including the canonical `mcpServers` shape, validation, scope precedence, resolution, and diagnostics. The Coding-Agent CLI adapter supplies a namespace-scoped config reader/writer, the process environment and workspace, a host-owned write-authorization callback, and a dedicated user-scoped MCP secret store implementing `McpSecretStore` for OAuth operations.
49
+
50
+ The API does not read or write files, resolve paths, decide whether a project is trusted, or create a secret store. Hosts provide those capabilities; the MCP package interprets only the MCP namespace. The CLI calls this API before starting the TUI or loading any Plugin runtime.
51
+
52
+ ## Public Plugin boundary
53
+
54
+ The MCP Plugin imports only public contracts from `@wincode/coding-agent`. It reads the host's generic namespace-scoped config snapshot for `mcp`, interprets the `mcpServers` data itself, and registers tools and status contributions through the generic Plugin API. The application injects the dedicated MCP secret store into the factory for MCP OAuth; generic Plugins own their other durable data and no generic host-managed Plugin secret store is exposed. Coding-Agent does not import MCP registry types or own MCP-specific UI. The package-level peer dependency exists for this adapter subpath; the client/domain and management contracts do not import Coding-Agent types.
55
+
56
+ Application entry points include the `@wincode/mcp/plugin` factory in the distribution and inject the host-managed MCP secret store; `--no-plugin mcp` disables it for one invocation. SDK callers may select a resolved file path with `pluginPaths`; however, the package's default `mcpPluginFactory` has no secret-store dependency, so that path alone does not enable MCP OAuth. For OAuth, provide a custom Plugin entry module that exports `createMcpPluginFactory({ createSecretStore })`, where `createSecretStore` returns a host-managed `McpSecretStore` for the supplied `userDataDir`, then select that module with `pluginPaths`. Keep MCP OAuth in this dedicated store rather than mixing it with Plugin-owned data.
57
+
58
+ Discovered tools marked hidden are omitted from the model-visible catalog and cannot be dispatched. Directly exposed MCP resources are available through the resource tools. Tool exposure controls visibility, not authorization; the host's Tool Gate remains a separate policy boundary. Use OS-level isolation when stronger process containment is required.