포트 없이 macOS용 로컬 도메인 https://<nama>.test.
devns add webui 8080
# ✓ https://webui.test → 127.0.0.1:8080 (caddy admin load HTTP 200)모든 것을 준비하는 단일 CLI: dnsmasq(와일드카드 *.test → 127.0.0.1), Caddy(포트 80/443의 유일한 소유자, 내부 CA를 통한 자동 HTTPS), 그리고 Secure DNS를 사용하는 브라우저에서도 .test 도메인을 열 수 있게 해주는 선택적 로컬 DoH 브리지.
devns 없이 | devns 사용 시 |
|
|
프로젝트 간 포트 충돌 | 프로젝트별 고유 이름, URL에 포트 없음 |
일반 HTTP | 신뢰할 수 있는 HTTPS( |
브라우저 Secure DNS가 로컬 도메인 차단 | DoH 브리지: |
Related MCP server: Domain Checker
필요: macOS + uv + Homebrew.
git clone https://github.com/apiep/devns && cd devns
uv tool install --editable .
devns init # sekali saja — minta sudo interaktif 2-3x
devns doh install # opsional: bridge DoH utk browser secure-DNSdevns init이 준비하는 것:
아직 없으면 brew install dnsmasq caddy
/etc/resolver/test → macOS가 TLD .test를 127.0.0.1로 라우팅
dnsmasq.conf의 address=/.test/127.0.0.1 블록 + :53의 service root
메인 Caddyfile(import ~/.config/devns/sites/*.caddy) + 80/443 service root
Caddy 내부 CA를 시스템 신뢰 저장소에 추가(sudo caddy trust)
DoH 브리지(AdGuard의 dnsproxy — OS/arch에 맞춰 바이너리 자동 다운로드)
일상적으로 sudo 전혀 없이: add/rm/ls/open/doctor/doh/log.
devns add pueue 7337 # daftarkan domain + reload Caddy + cek port
devns add api 3000 --open # sekalian buka browser
devns ls # ● https://pueue.test → 127.0.0.1:7337
devns open pueue # buka di browser default
devns rm pueue # hapus (konfirmasi; -y skip)
devns doctor # kesehatan: resolver/DNS/Caddy/HTTPS/DoH
devns doh install # bridge DoH (LaunchAgent user-level)
devns doh status
devns doh log -f # ikuti log dnsproxy livedevns doh install 후 Secure DNS를 Custom으로 설정: https://dns.test:8443/dns-query.
.test 쿼리는 로컬에서 응답하고, 다른 모든 쿼리는 선택한 업스트림 DoH(기본 OpenDNS)로 암호화되어 전달됩니다.
Browser ──DoH──> dns.test:8443 (dnsproxy, launchd io.devns.doh)
├─ [/test/] ──> dnsmasq :53 ──> 127.0.0.1
└─ lainnya ──> https://doh.opendns.com/dns-query
Browser ──HTTPS──> Caddy :443 ──reverse_proxy──> 127.0.0.1:<port-app>
──HTTP───> Caddy :80 ──308──> HTTPS
cert: Caddy Local Authority (tls internal), per-hostname on-demandRegistry: ~/.config/devns/registry.yaml = 유일한 진실의 원천
Site files: ~/.config/devns/sites/<nama>.caddy(생성된 산출물; 템플릿은 SSE 버퍼링을 방지하기 위해 flush_interval -1 사용)
일일 리로드: Caddy admin 엔드포인트 localhost:2019에 Content-Type: text/caddyfile 헤더 사용
devns는 추가 의존성 없이 stdio MCP 서버를 포함합니다:
hermes mcp add devns --command devns-mcp # Hermes Agent
# atau konfigurasi MCP client lain (Claude Desktop dsb) dengan command "devns-mcp"도구: list_domains, add_domain, remove_domain, check_health, doh_status.
이 저장소는 skills/devns/SKILL.md에 이식 가능한 스킬을 포함합니다(agentskills.io / Claude skills 형식). 에이전트의 skills 디렉터리에 복사하거나 symlink하세요.
와일드카드 *.test는 최신 검증기에서 거부됨 — Chrome과 curl은 SAN이 RFC상 유효하더라도 TLD에 직접 붙은 와일드카드 인증서를 거부합니다. 따라서 인증서는 Caddy 내부 CA가 호스트 이름별로 온디맨드 생성합니다.
포트 5353은 mDNSResponder(Bonjour)가 이미 사용 중 → DoH 브리지는 5335를 사용합니다.
/etc/resolver/test는 dnsmasq가 꺼져 있을 때 resolve를 중단시킵니다(빠른 실패가 아님) — 이는 버그가 아니라 resolver가 활성 상태라는 신호입니다.
MIT
Daftarkan nama.test -> 127.0.0.1:port lalu reload Caddy. Nama harus [a-z0-9-]. Contoh: add_domain(name='webui', port=8080)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | nama domain tanpa .test | |
| port | Yes | port lokal tujuan |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does mention the key side effect (reloads Caddy) and the required domain naming pattern. However, it omits details like idempotency, failure modes, or whether existing entries are overwritten, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action, followed by the naming constraint and an example. There is zero filler, and every part contributes to understanding the tool. It is exceptionally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the purpose, the side effect, naming rules, and an example. It is mostly complete, but it does not describe what the return value or success/failure indications look like, which would be helpful for an agent interpreting the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions are already clear (name without .test, local port), so baseline is 3. The description adds value by specifying the exact character pattern for name ([a-z0-9-]) and providing a concrete example, which goes beyond the schema. This elevates the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (register a .test domain pointing to 127.0.0.1:port) and explicitly mentions reloading Caddy, making it distinct from sibling tools like list_domains or remove_domain. The verb 'Daftarkan' and resource are clear, and the example reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a naming constraint ([a-z0-9-]) and a concrete example, which clarifies when and how to call it. It does not explicitly mention alternatives or exclusion scenarios, but the sibling names make the intended use obvious. The guidance is adequate, though not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cek kesehatan rantai devns: resolver, DNS, Caddy (admin + 80/443), HTTPS.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavior. It lists the components checked but does not state that the operation is read-only, whether it makes any changes, or what the output/return format is. An agent cannot infer side effects, permission requirements, or how to interpret results from this description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the action and resource, then lists the components. Every word earns its place, and the structure is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers the scope of what is checked. However, it does not explain what the result looks like (e.g., a summary, pass/fail, detailed diagnostics) or what 'health' means in practice. Since the output schema is absent, the description should provide at least a hint of return semantics, which it omits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema is trivially complete. The description inherently needs no parameter explanations. Per the rubric, a zero-parameter tool gets a baseline of 4, and there is no reason to deduct since the description adds no misleading or missing parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Cek kesehatan' = check health) and a specific resource ('rantai devns' = devns chain), and enumerates the components checked (resolver, DNS, Caddy, HTTPS). This clearly distinguishes it from siblings that manage domains (list_domains, add_domain, remove_domain) or check DoH status (doh_status). It is not a tautology and provides concrete scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what it does (checks health) but gives no guidance on when to use it versus alternatives. It does not mention whether to prefer this over doh_status for DoH-specific checks, nor does it specify prerequisites or typical scenarios. The context is implied ('health') but there is no explicit when/when-not or alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status bridge DoH lokal (dnsproxy via launchd).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, what side effects may occur, what the response format is, or any error conditions. For a status tool this is a critical omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no fluff, but it is under-specified. It is not effectively front-loaded because it fails to convey the tool's purpose clearly enough; brevity is achieved but at the cost of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no output schema), the description still needs to convey the tool's function and how it differs from check_health. It does not mention return values, read-only behavior, or the relationship to sibling tools, so an agent lacks critical information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does add context about the domain (DoH local bridge via dnsproxy/launchd) which helps an agent understand the subject, even though it does not explain any parameter (as there are none).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Status bridge DoH lokal (dnsproxy via launchd).' is a label-like phrase rather than a clear action. It names a resource (bridge DoH) and context (dnsproxy/launchd) but lacks an explicit verb like 'retrieve' or 'check', and does not distinguish it from the sibling check_health which likely serves a similar status purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus any of its siblings. No context is provided about the intended scenario or alternative tools, leaving an agent without any basis to select this tool over check_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daftar semua domain *.test terdaftar beserta port dan status port.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It describes a read operation (listing) but does not explicitly state that it is read-only, non-destructive, or free of side effects. It also does not mention any error conditions, rate limits, or data volume concerns. For a tool with no annotation coverage, more behavioral disclosure is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that front-loads the action (list all) and the resource (registered *.test domains) and includes the key output details. Every word earns its place; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description adequately specifies what the tool returns: registered domains, ports, and port status. It does not mention pagination, sorting, or limits, but for a simple list operation, this is not a critical omission. The description is sufficient for an agent to call and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to elaborate on them. The schema coverage is trivially 100% and there is nothing missing. The baseline of 4 applies because there are no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (list all) on a specific resource (registered *.test domains) and includes the details it returns (port and port status). It is clearly distinct from sibling tools like add_domain, remove_domain, check_health, and doh_status, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The name and description imply this is the tool for viewing all domains, but it does not mention alternatives like check_health or any conditions that would make another tool more suitable. The usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hapus nama.test dari registry + site Caddy, lalu reload.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. It states that the tool modifies a registry and a Caddy site and triggers a reload, which are relevant side effects. However, it does not mention irreversibility, permission requirements, or failure modes, so it's partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with the core action front-loaded. There is zero wasted text, and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter removal tool, the description covers the essential steps (remove, reload) but leaves out important context like whether the domain must exist, what happens on failure, or any safety caveats. Given the lack of an output schema and annotations, it is minimally complete but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the 'name' parameter. The phrase 'Hapus nama.test' implies that 'name' is the domain to remove, which gives basic meaning. However, it lacks format, examples, or edge-case details, so it only partially compensates for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove) and the resource (domain from registry and Caddy site) with a reload step. It is concise and unambiguous, though it does not explicitly contrast with sibling tools like add_domain, so it's not a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of conditions, prerequisites, or when not to use it. The name implies removal but that's not explicit enough for an agent to make a confident choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_domaincheck_healthdoh_statuslist_domainsremove_domainScored across 5 tools
Each tool serves a distinct purpose: listing, adding, removing domains, checking overall health, and checking DoH status. There is no overlap or ambiguity between the tools, making selection straightforward.
All tool names follow a consistent snake_case pattern with a verb_noun structure (list, add, remove, check) except 'doh_status' which is a noun phrase, but it still fits the naming style seamlessly. No mixed conventions or inconsistent verbs.
Five tools cover the complete lifecycle of managing local dev domains and health monitoring without being excessive or sparse. This is well-scoped for a developer-focused DNS and Caddy management server.
The tool set provides full CRUD for domains (list, add, remove) plus health checks for the entire system maintenance. There are no obvious missing operations required for the stated purpose; updates can be achieved by remove/add.
Validates domain email MX records and DNS status via Cloudflare DNS-over-HTTPS.
Manage Koru Shield DNS filtering: profiles, rules, categories, schedules, and logs.
Look up DNS information for any domain to troubleshoot issues and gather insights. Get fast, relia…
Custom domains for SaaS and AI agents: search, buy, connect DNS, verify ownership and issue HTTPS.
