Skip to content

Commit fcb8471

Browse files
oso95oso95
committed
init: domain-suite-mcp v0.1.0
MCP server for AI agents to autonomously manage domains and DNS. - 21 tools across 4 providers (Porkbun, Namecheap, GoDaddy, Cloudflare) - Zero-config domain availability checking via RDAP/WHOIS - Full domain lifecycle: register, DNS, SSL, email (SPF/DKIM/DMARC/MX) - 5 Claude Code skills installable via: npx domain-suite-mcp install - 161 unit tests passing
0 parents  commit fcb8471

61 files changed

Lines changed: 11104 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18.x, 20.x, 22.x]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Use Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
cache: npm
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Type check
30+
run: npm run typecheck
31+
32+
- name: Run tests
33+
run: npm test

‎.github/workflows/publish.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Publish to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
publish:
9+
runs-on: ubuntu-latest
10+
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Use Node.js
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: 22.x
18+
registry-url: https://registry.npmjs.org/
19+
cache: npm
20+
21+
- name: Install dependencies
22+
run: npm ci
23+
24+
- name: Type check
25+
run: npm run typecheck
26+
27+
- name: Run tests
28+
run: npm test
29+
30+
- name: Publish to npm
31+
run: npm publish --access public
32+
env:
33+
NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules/
2+
dist/
3+
*.js.map
4+
*.d.ts.map
5+
.env
6+
.env.*
7+
.claude
8+
spec.md

‎CHANGELOG.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2026-03-11
9+
10+
### Added
11+
12+
- 21 MCP tools for domain and DNS management
13+
- Four provider integrations: Porkbun, Namecheap, GoDaddy, Cloudflare
14+
- Zero-config domain availability checking via RDAP → public → WHOIS fallback chain
15+
- Email setup tools: `setup_spf`, `setup_dkim`, `setup_dmarc`, `setup_mx` with mail provider templates
16+
- SSL certificate management for Porkbun (full) and Cloudflare (list/status)
17+
- Domain transfer tools: `transfer_domain_in`, `get_transfer_status`
18+
- WHOIS contact management for Namecheap and GoDaddy
19+
- `setup_dkim` `keyType` parameter supporting `rsa` (default) and `ed25519`
20+
- SPF/DKIM/DMARC tools are idempotent: update existing records in place, return `previous` value when overwriting
21+
- `delete_dns_record` returns `{ success, id, domain }` confirmation
22+
- Namecheap sandbox support via `NAMECHEAP_SANDBOX=true`
23+
- GoDaddy OTE sandbox support via `GODADDY_SANDBOX=true`
24+
- Structured `AgentError` with `code`, `message`, `action`, `provider`, `raw` fields
25+
- All errors include actionable next steps for agents
26+
- Rate-limit handling: Bottleneck for Porkbun, automatic retry with `Retry-After` for GoDaddy
27+
- Namecheap IP auto-detection with public API fallback
28+
- Cloudflare DNS write note: warns about O(N) zone-ID lookup for large accounts
29+
- 161 unit tests across 13 test files
30+
- Integration smoke test against real Porkbun and Namecheap sandbox APIs
31+
32+
[0.1.0]: https://github.com/oso95/domain-suite-mcp/releases/tag/v0.1.0

‎CONTRIBUTING.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Contributing
2+
3+
Contributions are welcome. This guide covers how to set up the project, run tests, and submit a pull request.
4+
5+
## Prerequisites
6+
7+
- Node.js 18 or later
8+
- npm 9 or later
9+
10+
## Setup
11+
12+
```bash
13+
git clone https://github.com/oso95/domain-suite-mcp.git
14+
cd domain-suite-mcp
15+
npm install
16+
npm run build
17+
```
18+
19+
## Running Tests
20+
21+
```bash
22+
npm test
23+
```
24+
25+
All 161 unit tests must pass before opening a pull request.
26+
27+
## Type Checking
28+
29+
```bash
30+
npm run typecheck
31+
```
32+
33+
The project uses TypeScript strict mode. No type errors are permitted.
34+
35+
## Integration Testing
36+
37+
Integration tests run against real provider APIs and are opt-in:
38+
39+
```bash
40+
# Copy .env.example and fill in your API keys
41+
cp .env.example .env
42+
43+
# Run the smoke test
44+
node scripts/smoke-test.mjs
45+
```
46+
47+
Integration tests require real credentials. Namecheap sandbox (`NAMECHEAP_SANDBOX=true`) and GoDaddy OTE (`GODADDY_SANDBOX=true`) environments are safe for testing without incurring costs.
48+
49+
## Code Style
50+
51+
- TypeScript strict mode throughout
52+
- ESM modules (`"type": "module"`)
53+
- No `any` types
54+
- All errors must be `AgentError` instances with a `code`, `message`, and `action` field
55+
- Error messages must be actionable: tell the agent what went wrong and exactly what to do next
56+
57+
## Adding a Provider
58+
59+
1. Create `src/providers/<name>/client.ts` implementing the `Provider` interface from `src/providers/types.ts`
60+
2. Add provider config to `src/config.ts`
61+
3. Register the provider in `src/registry.ts`
62+
4. Add notes to `src/tools/providers.ts` (`SUPPORTED_NOTES`, `UNSUPPORTED_NOTES`)
63+
5. Add provider setup instructions to `docs/PROVIDERS.md`
64+
6. Update the provider table in `README.md`
65+
7. Add unit tests in `tests/unit/`
66+
67+
## Pull Request Guidelines
68+
69+
- One logical change per PR
70+
- Add or update unit tests for any changed behaviour
71+
- Update `docs/TOOLS.md` and `docs/PROVIDERS.md` if tool schemas or provider capabilities change
72+
- Add a CHANGELOG entry under `[Unreleased]`
73+
- Titles follow conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
74+
75+
## Reporting Issues
76+
77+
Open an issue with:
78+
- The tool name and input that caused the problem
79+
- The error output (sanitize any API keys)
80+
- The provider you are using

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 agent-domain-mcp contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)