@vucinatim/agentic-devtools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Vucina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Agentic Devtools
+
+Reusable developer tools for AI agents.
+
+Agentic Devtools is an MCP-first open-source package for developer platforms
+such as Railway, Namecheap, and npm. It is meant to be run directly by MCP hosts with
+`npx`, while still exposing package imports for custom automation.
+
+Most users should not install this into their app. Point your agent host at the
+tool you need:
+
+```bash
+npx -y @vucinatim/agentic-devtools mcp railway
+npx -y @vucinatim/agentic-devtools mcp namecheap
+npx -y @vucinatim/agentic-devtools mcp npm
+```
+
+Run the guided setup once if you do not want to put tokens in MCP host config:
+
+```bash
+npx -y @vucinatim/agentic-devtools connect railway
+npx -y @vucinatim/agentic-devtools connect namecheap
+npx -y @vucinatim/agentic-devtools connect npm
+```
+
+Start here:
+
+- [docs/architecture.md](docs/architecture.md)
+- [docs/usage.md](docs/usage.md)
+- [docs/auth-and-setup-guidelines.md](docs/auth-and-setup-guidelines.md)
+- [docs/open-source-readiness.md](docs/open-source-readiness.md)
+- [docs/publishing.md](docs/publishing.md)
+- [docs/migration-plan.md](docs/migration-plan.md)
+- [docs/testing.md](docs/testing.md)
+
+Project docs:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [LICENSE](LICENSE)
+
+## Repository Shape
+
+- `src/core/`
+  Shared CLI, registry, and result helpers.
+- `src/tools/<tool-name>/`
+  Service clients and MCP server entrypoints.
+- `adapters/codex/<tool-name>/`
+  Codex-specific plugin packaging and marketplace-facing metadata.
+- `adapters/claude/<tool-name>/`
+  Claude-facing adapter notes or future wrapper code.
+- `tests/tools/<tool-name>/`
+  Integration and protocol tests for each tool.
+- `.agents/plugins/marketplace.json`
+  Local Codex marketplace catalog for the Codex adapters in this repo.
+
+The package publishes as `@vucinatim/agentic-devtools` and exposes one CLI:
+`agentic-devtools`.
+
+## Usage
+
+### MCP Host Via `npx`
+
+This is the primary usage path.
+
+Railway:
+
+```json
+{
+  "mcpServers": {
+    "railway": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "railway"],
+      "env": {
+        "RAILWAY_API_TOKEN": "..."
+      }
+    }
+  }
+}
+```
+
+After `connect railway`, the same server config can omit `env` because the token
+is resolved from `~/.config/agentic-devtools/railway.json`.
+
+Namecheap:
+
+```json
+{
+  "mcpServers": {
+    "namecheap": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "namecheap"],
+      "env": {
+        "NAMECHEAP_API_USER": "...",
+        "NAMECHEAP_API_KEY": "...",
+        "NAMECHEAP_USERNAME": "...",
+        "NAMECHEAP_CLIENT_IP": "..."
+      }
+    }
+  }
+}
+```
+
+After `connect namecheap`, the same server config can omit `env` because
+credentials are resolved from `~/.config/agentic-devtools/namecheap.json`.
+
+npm:
+
+```json
+{
+  "mcpServers": {
+    "npm": {
+      "command": "npx",
+      "args": ["-y", "@vucinatim/agentic-devtools", "mcp", "npm"]
+    }
+  }
+}
+```
+
+Use `connect npm` for guided token setup. For real package releases, prefer
+GitHub Actions Trusted Publishing over local write tokens.
+
+### Global CLI
+
+Useful if you use the tools often from a terminal:
+
+```bash
+npm install -g @vucinatim/agentic-devtools
+agentic-devtools tools
+agentic-devtools connect railway
+agentic-devtools auth-status railway
+agentic-devtools mcp railway
+```
+
+### Project Dependency
+
+Use this only when building your own automation on top of the service clients:
+
+```bash
+npm install @vucinatim/agentic-devtools
+```
+
+```js
+import { createRailwayClient } from "@vucinatim/agentic-devtools";
+import { createNamecheapClient } from "@vucinatim/agentic-devtools";
+import { createNpmClient } from "@vucinatim/agentic-devtools";
+```
+
+## Design rule
+
+Keep the integration logic host-agnostic:
+
+1. build the service client and shared behavior in `src/`
+2. expose MCP from the same shared layer
+3. keep Codex and Claude wrappers thin and replaceable
+
+## Current plugins
+
+- `namecheap`
+- `railway`
+- `npm`
+
+## Development
+
+Current validation commands:
+
+```bash
+npm run build
+npm test
+npm run test:namecheap
+npm run test:railway
+npm run coverage
+npm run check
+```
+
+## Local Adapter Development
+
+Local Codex adapter entries point to:
+
+- `./adapters/codex/namecheap`
+- `./adapters/codex/railway`
+
+The shared MCP server implementations live at:
+
+- `src/tools/namecheap/mcp.mjs`
+- `src/tools/railway/mcp.mjs`
+
+Local CLI examples:
+
+```bash
+node src/cli.mjs tools
+node src/cli.mjs mcp railway
+node src/cli.mjs auth-status namecheap
+```
+
+## Publishing direction
+
+Publishing should use GitHub Actions and npm Trusted Publishing via OIDC. This
+avoids long-lived npm tokens and gives the public package provenance
+attestations.
+
+See [docs/publishing.md](docs/publishing.md).

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+Agentic Devtools connects agents to developer accounts and infrastructure. Treat
+credentials, destructive actions, and package publishing as high-risk surfaces.
+
+## Supported Versions
+
+This project has not published a stable version yet. Security fixes should
+target the main branch until the first public release.
+
+## Reporting A Vulnerability
+
+Do not open a public issue for credential exposure, auth bypasses, or unsafe
+write behavior.
+
+Report security issues privately to:
+
+```txt
+tim@vucina.com
+```
+
+Include:
+
+- affected tool
+- reproduction steps
+- expected impact
+- whether credentials or account data may be exposed
+
+## Credential Handling
+
+Never commit:
+
+- `.env`
+- `.env.*`
+- local Namecheap auth config files
+- Railway tokens
+- Namecheap API credentials
+- npm tokens
+
+Use environment variables or local ignored auth files for development.
+
+## Write Tool Policy
+
+Read-only tools are preferred by default.
+
+Write tools must be narrow, explicit, and tested. Destructive operations should
+make that behavior clear in the tool name, description, or input contract.

package/adapters/claude/namecheap/README.md

@@ -0,0 +1,13 @@
+# Claude Adapter
+
+This adapter does not currently need a Claude-specific wrapper.
+
+Use the published package directly:
+
+- `npx -y @vucinatim/agentic-devtools mcp namecheap`
+
+If Claude or another host needs packaging later, keep it thin:
+
+1. point the host to the shared MCP entrypoint
+2. avoid duplicating Namecheap client logic
+3. keep any host metadata inside this folder only

package/adapters/claude/npm/README.md

@@ -0,0 +1,11 @@
+# Claude Adapter
+
+Claude-facing adapters should wrap the published npm MCP runtime:
+
+- `npx -y @vucinatim/agentic-devtools mcp npm`
+
+Keep this adapter thin:
+
+1. reuse the shared npm client
+2. avoid duplicating registry API logic
+3. keep host-specific setup outside `src/`

package/adapters/claude/railway/README.md

@@ -0,0 +1,11 @@
+# Claude Adapter
+
+Claude-facing adapters should wrap the published Railway MCP runtime:
+
+- `npx -y @vucinatim/agentic-devtools mcp railway`
+
+Keep this adapter thin:
+
+1. reuse the shared Railway client
+2. avoid duplicating GraphQL logic
+3. keep host-specific setup outside `src/`

package/adapters/codex/namecheap/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "namecheap",
+  "version": "0.1.0",
+  "description": "Run the Agentic Devtools Namecheap MCP server from Codex.",
+  "author": {
+    "name": "Tim Vucina",
+    "email": "tim@vucina.com",
+    "url": "https://github.com/vucinatim"
+  },
+  "homepage": "https://www.namecheap.com/",
+  "repository": "https://github.com/vucinatim/agentic-devtools/tree/main/adapters/codex/namecheap",
+  "license": "MIT",
+  "keywords": [
+    "namecheap",
+    "domains",
+    "dns"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Namecheap",
+    "shortDescription": "Run Namecheap MCP tools from Agentic Devtools.",
+    "longDescription": "Connect Namecheap so Codex can inspect domains, read DNS state, and safely update host records through the published Agentic Devtools MCP runtime.",
+    "developerName": "Tim Vucina",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://www.namecheap.com/",
+    "privacyPolicyURL": "https://www.namecheap.com/legal/general/privacy-policy/",
+    "termsOfServiceURL": "https://www.namecheap.com/legal/universal/registration-agreement/",
+    "defaultPrompt": [
+      "Show me the DNS records for my domain.",
+      "Create a CNAME record for this subdomain.",
+      "Audit my Namecheap DNS setup for common issues."
+    ],
+    "brandColor": "#de3723"
+  }
+}

package/adapters/codex/namecheap/.mcp.json

@@ -0,0 +1,21 @@
+{
+  "mcpServers": {
+    "namecheap": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@vucinatim/agentic-devtools",
+        "mcp",
+        "namecheap"
+      ],
+      "env": {
+        "NAMECHEAP_API_USER": "[TODO]",
+        "NAMECHEAP_API_KEY": "[TODO]",
+        "NAMECHEAP_USERNAME": "[TODO]",
+        "NAMECHEAP_CLIENT_IP": "[TODO]",
+        "NAMECHEAP_API_SANDBOX": "[TODO: optional 1 for sandbox]",
+        "NAMECHEAP_API_BASE_URL": "[TODO: optional explicit override]"
+      }
+    }
+  }
+}

package/adapters/codex/namecheap/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: namecheap
+description: Use the Namecheap plugin to inspect domains, manage DNS records, and support domain configuration workflows through a small MCP surface.
+---
+
+# Namecheap
+
+Use this plugin when the user needs to work with Namecheap-managed domains or DNS.
+
+## Intended scope
+
+- Read domain details
+- Read and update DNS records
+- Support common setup flows such as verification, redirects, and subdomain configuration
+
+## Current MCP tools
+
+- `getAuthStatus`
+- `connectNamecheap`
+- `disconnectNamecheap`
+- `listDomains`
+- `getDomainDns`
+- `replaceDomainDns`
+- `addDomainDnsRecord`
+- `removeDomainDnsRecord`
+- `updateDomainDnsRecord`
+
+## Architecture note
+
+Keep the public plugin surface small:
+
+- expose stable MCP tools for domain and DNS operations
+- keep raw API handling inside the shared `src/` layer
+- add higher-level skills only after the MCP contract is stable
+
+## Auth model
+
+Namecheap uses API credentials plus IP whitelisting, not a normal OAuth token exchange.
+
+Use `connectNamecheap` to open a browser-based setup flow and store local plugin credentials, or provide credentials via environment variables if you need a stateless setup.

package/adapters/codex/npm/.codex-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "npm",
+  "version": "0.1.0",
+  "description": "Run the Agentic Devtools npm MCP server from Codex.",
+  "author": {
+    "name": "Tim Vucina",
+    "email": "tim@vucina.com",
+    "url": "https://github.com/vucinatim"
+  },
+  "homepage": "https://www.npmjs.com/",
+  "repository": "https://github.com/vucinatim/agentic-devtools/tree/main/adapters/codex/npm",
+  "license": "MIT",
+  "keywords": [
+    "npm",
+    "packages",
+    "publishing",
+    "registry"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "npm",
+    "shortDescription": "Run npm registry MCP tools from Agentic Devtools.",
+    "longDescription": "Connect npm so Codex can inspect package metadata, check package names, review token status, inspect publishing setup, and run explicit publish dry-runs through the published Agentic Devtools MCP runtime.",
+    "developerName": "Tim Vucina",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://www.npmjs.com/",
+    "privacyPolicyURL": "https://docs.npmjs.com/policies/privacy",
+    "termsOfServiceURL": "https://docs.npmjs.com/policies/terms",
+    "defaultPrompt": [
+      "Check whether this npm package name is available.",
+      "Show me the published versions and dist-tags for this package.",
+      "Run an npm publish dry-run for this package directory."
+    ],
+    "brandColor": "#cb3837"
+  }
+}

package/adapters/codex/npm/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "npm": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@vucinatim/agentic-devtools",
+        "mcp",
+        "npm"
+      ],
+      "env": {
+        "NPM_TOKEN": "[TODO: optional npm granular token]",
+        "NODE_AUTH_TOKEN": "[TODO: optional npm token fallback]",
+        "NPM_CONFIG_REGISTRY": "[TODO: optional registry override]"
+      }
+    }
+  }
+}

package/adapters/codex/npm/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: npm
+description: Use the npm plugin to inspect npm registry packages, package names, auth status, tokens, and publishing setup through Agentic Devtools.
+---
+
+# npm
+
+Use this plugin when the user needs to inspect npm packages, check whether a
+package name is available, validate npm auth, inspect token state, or run a
+publish dry-run.
+
+## Intended Scope
+
+- Read public package metadata
+- Check package name availability
+- List package versions and dist-tags
+- Check npm auth status without exposing tokens
+- Inspect token lists when an authenticated npm token is configured
+- Run local `npm publish --dry-run`
+- Run real local publishing only when explicitly confirmed
+
+## Current MCP Tools
+
+- `getNpmAuthStatus`
+- `connectNpm`
+- `disconnectNpm`
+- `testNpmConnection`
+- `getNpmPackageInfo`
+- `checkNpmPackageNameAvailability`
+- `getNpmPackageVersions`
+- `getNpmPackageDistTags`
+- `getNpmPackageVisibility`
+- `setNpmPackageAccess`
+- `listNpmTokens`
+- `exchangeNpmOidcToken`
+- `getNpmTrustedPublishers`
+- `addNpmGitHubTrustedPublisher`
+- `deleteNpmTrustedPublisher`
+- `publishNpmPackageDirectory`
+
+## Auth Model
+
+npm does not provide a normal third-party OAuth flow for local tools.
+
+Supported auth sources:
+
+- `NPM_TOKEN`
+- `NODE_AUTH_TOKEN`
+- explicit npm user config via `.npmrc`
+- local Agentic Devtools storage from `connectNpm`
+
+Prefer GitHub Actions Trusted Publishing for real package releases. Local
+publishing is available for controlled cases, but it requires an explicit
+confirmation string.

package/adapters/codex/railway/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "railway",
+  "version": "0.1.0",
+  "description": "Run the Agentic Devtools Railway MCP server from Codex.",
+  "author": {
+    "name": "Tim Vucina",
+    "email": "tim@vucina.com",
+    "url": "https://github.com/vucinatim"
+  },
+  "homepage": "https://railway.com/",
+  "repository": "https://github.com/vucinatim/agentic-devtools/tree/main/adapters/codex/railway",
+  "license": "MIT",
+  "keywords": [
+    "railway",
+    "deployments",
+    "infrastructure"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Railway",
+    "shortDescription": "Run Railway MCP tools from Agentic Devtools.",
+    "longDescription": "Connect Railway so Codex can inspect account identity, projects, environments, service instances, domains, and deployment status through the published Agentic Devtools MCP runtime.",
+    "developerName": "Tim Vucina",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://railway.com/",
+    "privacyPolicyURL": "https://railway.com/legal/privacy",
+    "termsOfServiceURL": "https://railway.com/legal/terms",
+    "defaultPrompt": [
+      "Show me my Railway projects.",
+      "Inspect this Railway project's production environment.",
+      "Check the deployment status for this Railway project."
+    ],
+    "brandColor": "#0b0d0e"
+  }
+}

package/adapters/codex/railway/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "railway": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@vucinatim/agentic-devtools",
+        "mcp",
+        "railway"
+      ],
+      "env": {
+        "RAILWAY_PROJECT_TOKEN": "[TODO: optional project-scoped token]",
+        "RAILWAY_API_TOKEN": "[TODO: optional account-scoped token]",
+        "RAILWAY_TOKEN": "[TODO: optional account-scoped token fallback]",
+        "RAILWAY_PROJECT_ID": "[TODO: optional default project id]",
+        "RAILWAY_API_ENDPOINT": "[TODO: optional explicit GraphQL endpoint override]"
+      }
+    }
+  }
+}

package/adapters/codex/railway/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: railway
+description: Use the Railway plugin to inspect Railway account, project, environment, service, domain, and deployment state through a small read-only MCP surface.
+---
+
+# Railway
+
+Use this plugin when the user needs to inspect Railway projects, environments,
+services, domains, or deployment status.
+
+## Intended Scope
+
+- Read account identity
+- List Railway projects
+- Inspect a project and its environments
+- Inspect environment service instances and deployment status
+- Run a compact project doctor summary
+
+## Current MCP Tools
+
+- `getRailwayAuthStatus`
+- `testRailwayConnection`
+- `getRailwayViewer`
+- `listRailwayProjects`
+- `inspectRailwayProjectToken`
+- `getRailwayProject`
+- `listRailwayEnvironments`
+- `getRailwayEnvironment`
+- `doctorRailwayProject`
+
+## Architecture Note
+
+Keep the public plugin surface read-only until write workflows have explicit
+confirmation and rollback rules.
+
+## Auth Model
+
+Railway supports different token scopes.
+
+- `RAILWAY_PROJECT_TOKEN` is project-scoped and works for project inspection.
+- `RAILWAY_API_TOKEN` or `RAILWAY_TOKEN` is account-scoped and works for account
+  identity and project listing.
+
+Prefer project tokens for narrow inspection when a specific project is known.

package/docs/README.md

@@ -0,0 +1,14 @@
+# Docs
+
+Start with:
+
+- [Architecture](architecture.md)
+- [Usage](usage.md)
+- [Auth And Setup Guidelines](auth-and-setup-guidelines.md)
+- [Open Source Readiness](open-source-readiness.md)
+- [Publishing](publishing.md)
+- [Migration Plan](migration-plan.md)
+- [Testing](testing.md)
+
+These docs describe the public package direction and the current repository
+setup.