technitium-mcp

command module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: GPL-3.0 Imports: 4 Imported by: 0

README

technitium-mcp - a Technitium DNS Server MCP server, CLI and Go SDK

GitHub release Go Version License build tests lint coverage

An MCP server, CLI and Go SDK for Technitium DNS Server, so a model working on a network can see what its DNS servers hold, compare servers that are meant to agree, and find what is wrong - from Claude Code, Claude Desktop, or any other MCP client - without falling back to dig and guesswork.

Wrapping the API lets a model browse a DNS server. The reason this exists is the layer above: audits, each a sweep over every zone on every server for one kind of thing that goes wrong - a zone one server has and the other does not, a CNAME to a name with no record, an address whose PTR names another host, a record that is never served because a zone further down answers instead - returning a worklist with the fix beside each finding.

The whole server is covered. The SDK wraps every one of the 139 calls in Technitium's API document and can send every parameter the document gives them, and 106 tools put them to use: zones and records of every type, the cache, blocking, DHCP, DNSSEC, clusters, accounts and permissions, apps, settings, backups and logs. Each is tested against real servers.

What is in the box
  • Several servers, side by side. One process works on every server you name. A read asks all of them and sets the answers beside each other, so a zone one server lacks, or a record two servers hold differently, shows without comparing by hand. A server that is down is said beside the answers of the ones that are up.
  • Reads only, until told otherwise. No tool that changes a server is registered without --enable-write, and none that deletes without --enable-delete beside it. Every change takes dry_run, which says what would be done and sends nothing, and answers with what it did read back from the server: a Technitium server says ok to things it did not do.
  • A Go SDK. sdk/technitium is a typed client for the Technitium API, standard library and go-kt only, with no knowledge of MCP. Technitium publishes no OpenAPI document, so it is written by hand from the server's API document, which is vendored under api-defs/ and held against the client by the tests, both ways: every call the client makes and every parameter it sends is one the document has, and every call and every parameter the document has is one a test of the client sends.
  • Tested against real servers, three ways. Every tool and every SDK method runs against real Technitium servers in Docker: on one server, on two that know nothing of each other, and on two made a cluster through the API during the run. Each run fails if a registered tool was never seen to answer. The leases the DHCP tools are tested on are real ones: a small DHCP client is run on the test servers' own network and asks for them.
The audits
audit what it finds
audit_all every audit in one reading of the servers, counts only: where to look first
audit_servers where servers meant to hold the same do not: a zone one lacks (and, in a cluster, that it is not in the catalog the other node follows), a zone two servers each hold as their own primary, the records that differ, a copy behind its primary or whose transfer failed or that has expired
audit_targets records that point at a name and end nowhere: a CNAME to a name with no record, a loop, a long chain, a CNAME at a zone's own name or beside other records, an MX, SRV or NS whose target is missing or is a CNAME
audit_reverse addresses and PTRs that disagree: an address with no PTR (with the call that adds it), a PTR naming a host that does not hold the address, several PTRs for one address, a network with addresses in use and no reverse zone
audit_overlaps records never served because a zone further down on the same server answers for the name; one name with addresses in two networks; the odd public address in a zone of private ones, or the reverse; and every wildcard, which makes a mistyped name resolve
audit_naming probable slips: a stray space or invisible character, an underscore in a host name, two names a typing slip apart, a TTL under a minute, over a week, or far from the one the rest of its zone has, and one host's names written two ways (emby-dock beside jf.dock)
audit_state what is switched off or set to vanish: disabled zones and records, records set to delete themselves
audit_zones a zone's own records and options against the servers that hold it: a name server it names that is none of them and no node of their cluster, a holder none of its NS records names, an SOA naming a primary that is not the server holding it as one - what a renamed server leaves behind - and a primary that gives its copies no transfer or no word of a change; reverse zones of one address each, and ones with no PTR in them
audit_security what is left open: a server resolving for anyone, a console over plain HTTP alone, the password a server ships with, a zone anyone may transfer or change with no key, an API token unused for ninety days, a server behind the version that is out
audit_access accounts and permissions that make a server easier to take than it need be: an administrator who signs in with a password alone, an account nobody has ever used, a switched-off account whose tokens are still there, the admin account the server ships with left on beside another administrator, a section every account may change
audit_cluster a cluster that is not whole: a node the others cannot reach, nodes that do not agree who the nodes are, a secondary that has stopped fetching the configuration, nodes on different versions, a cluster of one, a node that is not configured here and so was read by no audit, and a server left outside a cluster the others are in
audit_dnssec what the keys of the signed zones are waiting for or leave weak: a key that waits for its DS record at the parent zone, a key made and never put in the zone, a zone whose names anyone can list, a zone signing key the server never replaces, an algorithm no longer trusted, signatures the server has let expire
audit_queries what the servers' resolving and the last day of queries say is wrong: a server that cannot resolve a name right now, a forwarder of its that does not answer, fails or is slow (each is asked), a server with no log of queries, one answering too much with a failure, one client asking for most of everything, a busy client with no name, a name asked for far more often than its TTL allows, and the names in the servers' own zones that clients keep asking for and that do not exist
audit_apps the DNS apps the servers run: an app behind the version the store has, an app one server runs and another does not, and one they run at different versions or configured differently
audit_blocking what the servers block: blocking switched off or paused with lists still set, block lists not fetched or holding nothing, a blocked name that blocks nothing because a zone on the server answers for it or an allowed entry wins, an entry another already stands for, and servers that do not block alike
audit_dhcp DHCP against itself and against the zones: one server leasing alone, two leasing the same addresses, a scope running out, naming name servers that are not these or naming one server twice, reservations that cannot work (an address outside the network, a hardware address of all zeros) or have no name in DNS, a record made by hand at an address a scope gives out or has given to another machine, and records the server wrote for a lease that is gone
audit_split the inside and the outside of a split horizon, by asking a resolver you name for every name the zones hold: an override whose public name is gone, a private address the outside is given, a name that resolves outside and has no record here, and a parallel domain that does not answer as the zone it mirrors. Not part of audit_all: it asks other people's name servers
audit_names a list of host names - every name a reverse proxy routes - each said to have records and where it ends, or why not

audit_all runs every one but audit_split, which asks other people's name servers, and audit_names, which checks a list you give it.

Installation

go install github.com/katbyte/technitium-mcp@latest

The servers must be Technitium DNS Server 15.0 or newer: the token is sent as a header, which older servers do not read. Both live suites pass on 15.5 and 15.6; the versions from 15.0 to 15.4 have not been run.

Configuration

Make an API token on each server: web console, Administration, Sessions, Create Token. The token acts as the user it is made for. A user who is not an administrator sees only the zones whose own permissions name them, and none of the accounts, so an administrator's token is the simple way: technitium-mcp only reads unless --enable-write is given. server_info says what the token may do on each server.

Settings come from flags, TECHNITIUM_* environment variables, or a configuration file.

flag environment
--server, -s TECHNITIUM_SERVER the address a web console answers on, or several as name=url
--token, -t TECHNITIUM_TOKEN one token for every server, or one each as name=token
--enable-write TECHNITIUM_ENABLE_WRITE register the tools that change a server; without it every tool only reads
--enable-delete TECHNITIUM_ENABLE_DELETE register the tools that delete as well; needs --enable-write
--read-only TECHNITIUM_READ_ONLY the default, said out loud, for a start line shared with the other servers; refused beside --enable-write
--toolsets TECHNITIUM_TOOLSETS groups of tools: all, core (the default, and always included), audit, ops, edit, block, dhcp, dnssec, cluster, admin, apps, or a family like zone
--allow-tools TECHNITIUM_ALLOW_TOOLS tools to add to the toolsets, by name or a glob like zone_*: --toolsets core --allow-tools zone_get is core and that one tool. With no --toolsets, only the tools named are registered
--deny-tools TECHNITIUM_DENY_TOOLS tools never to register, by name or glob: how a toolset is narrowed
--listen TECHNITIUM_LISTEN serve MCP over HTTP at this address instead of stdio
--auth-token TECHNITIUM_AUTH_TOKEN the bearer token HTTP clients must send; required with --listen unless --allow-no-auth
--allow-no-auth TECHNITIUM_ALLOW_NO_AUTH serve HTTP with no bearer token: anyone who can reach the port can use every tool

TECHNITIUM_LOG sets the log level (info, debug, trace); unset, only warnings and errors are logged. At info and below, one line is logged for every call of a tool that changes or deletes: the tool, what it was sent with passwords, codes and keys blanked, and whether it answered, was refused or failed. A dry run is told apart by its dry_run argument.

Configuration file

A .technitium-mcp file in $HOME, and one in the working directory read over it key by key, so a project's file needs only the settings it changes. Keys are the environment variable names, with or without the TECHNITIUM_ prefix. A flag or an environment variable beats either file.

# one server
SERVER=http://nas:5380
TOKEN=<token>
# several, each under a name the tools take
SERVER=ns1=http://192.168.1.2:5380,ns2=http://192.168.1.3:5380
TOKEN=ns1=<token>,ns2=<token>

Every node of a cluster is configured by its own address. The API has a way to ask one node through another, and the SDK wraps it (OnNode), but the servers pass on only half their calls that way - not the list of zones, the settings or anything of DHCP - so a node reached through another could answer only some of the tools.

Usage

technitium-mcp info     # each server's name, version and account, or why it cannot be asked
technitium-mcp tools    # what would be registered with the current settings
technitium-mcp serve    # the MCP server, on stdio
Register with Claude Code

.mcp.json:

{ "mcpServers": { "technitium": { "command": "technitium-mcp", "args": ["serve"] } } }
Run as a service (HTTP transport)

serve --listen :8080 serves the MCP Streamable HTTP transport at /mcp (and GET /healthz) instead of stdio. Clients must send Authorization: Bearer <token> with the token TECHNITIUM_AUTH_TOKEN holds, and the server refuses to start without one unless --allow-no-auth says anyone who can reach the port may use every tool.

claude mcp add --transport http technitium http://nas:8080/mcp --header "Authorization: Bearer $TECHNITIUM_AUTH_TOKEN"
Docker

docker-compose.yml runs the released image as an always-on HTTP server, reading its secrets from a gitignored .env; see .env.example. make docker builds the same image from source.

MCP Tools

Tools are named for what they act on (zone_*, record_*, dhcp_*, user_*...) and grouped into toolsets by the job someone is doing. Every tool takes server: a read asks every configured server unless one is named, and a change is made on one named server at a time. The needs column says which switch registers a tool: nothing for a read, write for --enable-write, delete for --enable-delete beside it.

core: what the servers are and what they hold: loaded always
tool needs what it does
server_info each configured server: the name it is configured under, its own domain name, version, whether an update is out, when it started, its cluster, and the account the token acts as with what that account may not read, change or delete. A server that cannot be reached is listed with the reason. Start here
zone_list the zones on every server, one row a zone: its type, serial, whether disabled or signed, when it last changed, a secondary's transfer state - as each server holds it, with which servers lack it and what differs between the copies. counts adds each copy's size
zone_records one zone's records from every server holding it, as one table: a record held alike is one row, and one only some servers hold (or hold with another TTL or comment) names them. Filters by type, name, value, comment and state; summary for counts; limit and offset to page
record_find records across every zone at once. By address: what holds it, its PTR, and everything that ends at it through a chain of CNAMEs - what a change of address would touch, or whether an address is free. By target: what points at a name. Or by name, value, type or comment
dns_resolve what each server really answers for a name, side by side: the result, every CNAME on the way, the TTL, whether it came from its own zone, and when the server blocked it, by which list. Asks other resolvers the same from each server, to see what the outside world is told
cache_get what each server's cache is keeping for a name: the answer, how long it has left, where it came from, and whether it is the answer that the name does not exist
audit_names a list of host names - every name a reverse proxy routes - each said to have records and where it ends, or why not
audit: find what is wrong

The seventeen audit_* tools in the table above, every one of them a read. audit_names is in core.

ops: how the servers are set up, what they are doing, and keeping one running
tool needs what it does
server_settings how each server is set up, side by side, and which settings they do not have alike: where it answers, whose queries it resolves and through what, transfers and keys by name, blocking, TTLs, console, log, apps. No secret is among them
settings_get every setting a server has, the hundred and thirty or so behind the console's Settings pages, by the name the API gives it, side by side where the servers differ. Nothing secret is given
server_stats what each server did over the last hour, day, week, month or year, or between two times: queries and clients, how they were answered and from where, the part that failed, did not exist or was blocked, and the clients and names that lead
server_metrics whether each server can resolve a name right now - its own health check - how long it has been up, and every query it has answered since it started, by how and from where; the same counters as Prometheus reads them when asked
log_search the servers' logs of the queries they answered: who asked for what, when, and what they were told, filtered by name, client, type, result, source and time - or counted by client or by name, for who is still asking for an old name and which names do not exist. Needs the Query Logs app on the server, and says so when it is missing
log_export the log of queries as CSV, for what log_search would find: for handing on to a spreadsheet or another tool
log_files the files each server writes its own log to, a file a day
log_read a server's own log for a day: its end, or only the lines with some text in them. Where a failure explains itself - why a transfer was refused, why a block list was not fetched, who signed in and what they changed
zone_get how one zone is served and copied on each server holding it: its type and catalog, what its SOA and NS records name, who may ask, transfer and update and with which keys, who is told of a change, and for a copy where it transfers from
zone_export one zone whole as a zone file, comments included: a copy to keep before a change, or to take elsewhere
settings_backup writes a backup of a server - all of it, or the parts named - to a zip file on the machine the tool runs on, readable by its owner alone and never over a file that is there. The server is only read
settings_set write changes any setting by the name settings_get gives it. Only what differs is sent, a name the server does not know is refused, and a value the server rewrote or passed over is said
tsig_key_set write adds a transfer key (TSIG) or changes one, leaving the server's other keys as they are. The secret is never read back
tsig_key_delete delete takes a transfer key off a server, leaving the rest
settings_restore delete puts parts of a server back from a backup's zip file, writing over what the server has of each. With a dry run, lists what the backup holds
stats_delete delete deletes every statistic a server keeps: the dashboard starts again from nothing
log_delete delete deletes one of a server's own log files, or all of them
edit: change what the zones hold
tool needs what it does
record_set write makes a record be there with the value given: added, changed in place, or left alone when it already is. Every record type the server has, from its one line: the common ones, HTTPS and SVCB, TLSA, SSHFP, DS, NAPTR, URI and RP, the server's own FWD (a name sent on to another name server) and APP (a name answered by an installed app), and any other type as bytes. What a type has beside its value - an NS record's glue, how a forwarder is reached, what an app is told - goes in options, and a record changed keeps what it has. Keeps the TTL and comment of what it changes, and of the records beside it, which the server would otherwise drop. Sets the PTR too when asked, at the same TTL
record_repoint write moves every record at one address to another across all zones, with the PTRs: for a host that changes address. Refused when the new address belongs to another name unless share says so; dry_run lists every change
cache_flush write drops what a cache keeps for a name and everything under it, on one server or all
zone_create write makes a zone of any of the server's seven types: a primary, a secondary or a stub that copies another server's, a forwarder with how its name server is reached (or empty, to put FWD records in), a catalog, or a copy of another server's catalog or forwarder; a reverse zone by its network (10.0.0.0/24); a member of a cluster's catalog when asked. Says what else the change does
zone_edit write changes how a zone is served: who may ask, transfer and update it and with which lists, the keys a transfer may be signed with and the keys an update must be signed with and what each may change, who is told of a change, on or off, its catalog and what it keeps its own setting for, a copy's primary and how it transfers, what its SOA says and whether it numbers its changes by the day. Reads the zone back, because the server says ok to options it does not take
zone_resync write has a server transfer its copy of a zone from the primary again now
zone_clone write makes a zone that is another's copy at the time, on the same server: a zone from a template, or the first half of a rename
zone_convert write turns a zone into another type where it stands, keeping its records: a secondary into a primary when the server it copied from is gone
zone_import write adds the records of a zone file to a zone: beside what is there, in place of the names it holds, or in place of the whole zone
dns_import write copies a name's records in from another name server: the server asks for the name and writes the answer into the zone it holds for it. A zone held somewhere else, brought over a name at a time with nothing typed by hand
record_delete delete deletes a record and answers with it as it was, which is what puts it back
zone_delete delete deletes a whole zone with every record in it, saying first what it holds. A zone the server made for itself is refused
block: what the servers refuse to resolve, and why
tool needs what it does
block_check whether each server blocks a name and what makes it so: its own blocked list or a block list it fetches, by entry; and for an entry that does not block the name, why not - an allowed entry over it, blocking off or paused, or a zone on the server answering for the name
block_list how each server's blocking stands - on, off or paused, how a blocked name is answered, the lists fetched and how many names they hold - and every entry of its own blocked and allowed lists, with what the servers do not have alike
block_tree walks a blocked or allowed list as the tree it is kept as: whether a name is on it, and the names under it that are. For a list too long to read whole
block_set write puts a name on a server's blocked list, or on its allowed list to let it past whatever blocks it; then asks the server for the name and says whether it is blocked now, and if a blocked entry does nothing, why
block_switch write switches blocking on or off, or pauses it for some minutes: the way to find out whether blocking is what breaks something
block_lists_set write sets the block lists a server fetches, whole or one at a time, and has it fetch them now
block_import write adds many names at once to the blocked or the allowed list; names already there are left alone
block_delete delete takes an entry off the blocked or the allowed list, and says how the name stands afterwards: a block list can block it still
block_flush delete empties the blocked or the allowed list, every name at once
dhcp: the addresses the servers lease
tool needs what it does
dhcp_scopes each server's DHCP scopes: the range and what it leaves out, whether it is on and on which address, the gateway, name servers and domain machines are given, whether leases are recorded in DNS, and how many addresses are free, leased and reserved. Says which servers lease at all
dhcp_leases the machines: every lease, dynamic or reserved, with hardware address, name and expiry, and every reservation nobody holds. find looks one up by name, address or hardware address however it is written: what has this address, where is this machine
dhcp_reservation_set write keeps an address for a machine: pin this host. Added, replaced, or left alone when it already is. Refuses what the server would take and could not work: an address outside the scope's network, the server's or the gateway's, one kept for or held by another machine. Says, before it is done, when the server will write the name over a record made by hand
dhcp_lease_reserve write turns the lease a machine holds into a reservation, so the address it has now is the one it keeps; or a reserved lease back into an ordinary one
dhcp_scope_set write makes a DHCP scope or changes one: range, exclusions, lease time, gateway, name servers, domain, on or off, and the rest of what a scope hands out - time servers, search domains, static routes, the boot server and file, vendor and numbered options - with how it leases (ping first, wait before offering, refuse made-up hardware addresses). Renames one. A new scope is left off unless asked otherwise, and a range another server here already leases is refused
dhcp_reservation_delete delete removes a reservation and answers with it as it was, and with the records the server took out of DNS with it
dhcp_lease_delete delete has a server forget a lease, for a machine that is gone. The server drops a reservation with its lease; this puts the reservation back
dhcp_scope_delete delete deletes a scope with its reservations and leases, counted first
dnssec: sign a zone and look after its keys
tool needs what it does
dnssec_get how a zone is signed on each server holding it: every key with its state and when the server next replaces it, how the zone proves a name is not there, and the DS records to give the registrar
dnssec_sign write signs a primary zone: the keys, the algorithm and how absence is proved as asked, and the DS record for the parent zone in the answer
dnssec_edit write changes how a signed zone proves a name is not there (NSEC, or NSEC3 with its iterations and salt) and the TTL of its DNSKEY records
dnssec_key_add write adds a key signing key or a zone signing key to a signed zone
dnssec_key_edit write moves a zone's keys along: publishes the ones only generated, rolls one over to a new key, retires one, or sets how often the server replaces one by itself. What the server refuses as not safe yet is said with its reason
dnssec_key_delete delete deletes a key that was generated and never published
dnssec_unsign delete takes DNSSEC off a zone: its keys are deleted for good. With a dry run, lists the keys that would go
cluster: make, grow, shrink and end a cluster
tool needs what it does
cluster_get how each server stands in a cluster: whether it is in one, primary or secondary, every node as it sees it with when it last fetched the configuration, and how often the nodes look at each other
cluster_create write makes a server the primary node of a new cluster; nothing it holds is lost
cluster_join write has a server join a cluster as a secondary: its settings, apps and accounts are written over with the primary's, its zones and scopes kept
cluster_edit write changes how a cluster runs: the times its nodes keep, the addresses a node is reached at, where a secondary finds its primary, and a fetch of the whole configuration now
cluster_promote write makes a secondary the cluster's primary: how a primary is moved or retired, and with force how a cluster is saved when its primary is lost
cluster_node_delete delete takes a secondary out of a cluster, asked of the primary: by asking the node to leave, or with force dropping one that no longer exists
cluster_leave delete takes a secondary out of its cluster, asked of that node; it keeps what it holds
cluster_delete delete deletes a cluster, asked of its primary, once no secondary is left; the server keeps everything but its place in one
admin: who may sign in and what each may do
tool needs what it does
user_list the accounts on each server, side by side: which are switched off, when each last signed in, and which servers have each
user_get one account whole: its groups, whether it has a second factor, who is signed in as it, and its API tokens by name with when each was last used and from where
group_list the groups on each server and who is in each
session_list who is signed in to each server and every API token made on it: everything that can act on a server without a password. Nothing of a token but its start is given
access_get who may view, modify and delete in each section of a server, or with one zone: by group, and by account where one is named
sso_get how each server is set up for single sign-on (OpenID Connect). The client's secret is never read
account_get the account the tool itself works under on each server: its groups, which is what the tool may do there, and its sessions and tokens
user_set write makes an account or changes one: its password, name, groups, whether it is switched off, how long its sessions last. Refuses to switch off the account the tool works under, or to take it out of the administrators
group_set write makes a group or changes one: what it is for, who is in it, its name
token_create write makes an API token for an account. The answer holds the token, once
access_set write gives an account or a group view, modify and delete in a section or with a zone, changes what one has, or takes one off the list; whoever is not named is left as they are
sso_set write changes how a server is set up for single sign-on
account_edit write changes an account as the account itself, by signing in with its name and password: its password, a second factor put on or taken off, a token of its own, one of its sessions ended. The things a server lets only an account's owner do
user_delete delete deletes an account with every session and token it had. The account the tool works under is refused
group_delete delete deletes a group; its members keep their accounts and lose what the group gave them
session_delete delete ends one session or deletes one API token, by its id. The token the tool works under is refused
apps: the DNS apps a server runs
tool needs what it does
app_list the DNS apps installed on each server, with version and parts; with store, which have a newer version at the server's maker's store and what else it offers
app_config_get an installed app's configuration on each server, side by side, with whether they differ
app_install write installs an app, or updates the one installed under the name keeping its configuration: from the store by name, from an address the server fetches, or from a zip file sent to it
app_config_set write writes an app's configuration, whole, and answers with what it was. Text that is not JSON is refused where the configuration was JSON
app_delete delete uninstalls an app, with its configuration and whatever it kept
Choosing which tools load

The default is core: seven read-only tools, about 3,000 tokens. Every tool's name, description and input schema is spent from a client's context before anyone has asked a question, and the whole surface is about 41,000 tokens, so --toolsets / TECHNITIUM_TOOLSETS loads the groups a session needs. core comes along with whatever else is asked for, because no other set can find a zone or read a record on its own.

toolset tools, reading ~tokens with --enable-write --enable-delete ~tokens
core (default) 7 3,000 7 3,000
audit 24 10,700 24 10,700
ops 18 6,600 24 8,400
edit 7 3,000 19 9,800
block 10 3,800 16 5,700
dhcp 9 3,600 15 6,900
dnssec 8 3,200 14 5,400
cluster 8 3,200 15 5,700
admin 14 4,200 23 7,700
apps 9 3,400 12 4,300
all 51 17,800 106 40,900

Each row counts core with the set. Tokens are what the model sees, measured over a real tools/list at four bytes a token. Every tool also carries an output schema, another 56,000 tokens across all, which clients keep to themselves to check results rather than sending to the model.

--toolsets also takes a family, which is every tool whose name starts with it: zone, record, dhcp, user, app and so on.

TECHNITIUM_TOOLSETS=audit                 # find what is wrong, nothing that writes
TECHNITIUM_TOOLSETS=ops,block             # how the servers run and what they block
TECHNITIUM_TOOLSETS=edit,dhcp TECHNITIUM_ENABLE_WRITE=true   # change records and reservations
TECHNITIUM_TOOLSETS=core TECHNITIUM_ALLOW_TOOLS=zone_get     # core and one tool more
TECHNITIUM_TOOLSETS=all TECHNITIUM_DENY_TOOLS='cluster_*'    # everything but the cluster tools

--allow-tools also takes the essential preset (server_info, zone_list, zone_records). A name or pattern that matches no tool stops the start and says which, so a typing slip cannot hide a tool. Neither flag gets a tool past the write and delete switches.

What a change does before it is made
  • dry_run on every change. It says what would be done, in the words the real call uses, and sends nothing. It does not check whether the token may make the change: the server says that when the change is made.
  • Read back. A change answers with what the server holds afterwards, and a server that said ok without doing it is an error that says so.
  • The tool will not lock itself out. The account the tool works under is not switched off, deleted or taken out of the administrators; its own token is not deleted; the Administrators group is not given less than everything.
  • No secret in any answer. Passwords, token values, transfer keys' secrets and the single sign-on secret are sent and never read back; a token is shown once, when it is made.
  • A backup is of what the server has written to disk, which lags a change by a few seconds: one taken straight after a change can miss it. A backup holds the server's secrets, and the file is written for its owner's eyes only.

Using the client on its own

sdk/technitium is a plain Go client for the Technitium API with no knowledge of MCP. Beneath it are the standard library and go-kt's HTTP package, which itself uses only the standard library. To talk to a Technitium server from Go, take it and ignore the rest:

import "github.com/katbyte/technitium-mcp/sdk/technitium"

client, err := technitium.New("http://nas:5380", os.Getenv("TECHNITIUM_TOKEN"))
zones, err := client.Zones(ctx, technitium.ZoneFilter{})

It has 160 methods covering every one of the 139 calls in Technitium's API document, and every parameter the document gives them. make apicheck reads the calls out of the vendored document and says how many are wrapped. The unit tests fail when a call the client makes is not the document's, when a parameter it sends is not one the document gives the call, when a secret is sent in an address rather than a body, when a method has no test - and when a parameter the document gives a call is sent by no test, unless it is listed with why in api-defs/unsent.txt, which holds five names the server no longer reads. Every method is also run against a real server.

Records of every type are written from one line, as a zone file writes them:

data, err := technitium.ParseValue("HTTPS", "1 . alpn=h2,h3")
rec, err := client.AddRecord(ctx, technitium.NewRecord{Zone: "example.com", Name: "www.example.com", Type: "HTTPS", TTL: 300, Data: data})

A read is asked for again when the connection dropped or a gateway in front of the server could not reach it; a write is sent once. A call is given two minutes: the server sends nothing of an answer until the call is done, and a server joining a cluster or a backup being restored takes as long as there is to do. A redirect is refused rather than followed, since following one turns a write into a read with nothing in it. Nothing is logged unless the client is handed a logger, and then every request and answer is traced with the token, passwords and keys blanked.

What the document gets wrong or leaves out, found by running against real servers, is written down in api-defs/README.md.

Development

make tools      # build the pinned dev tools into .tools/bin
make build      # compile, with the version from git
make test       # unit tests with the race detector: canned servers, and the client against the API document
make testacc    # both live suites on real Technitium servers in Docker: one, then two, then the two as a cluster
make lint       # golangci-lint with the azproviderlint plugin
make apicheck   # how much of the Technitium API the SDK wraps
make check-all  # everything
where what
sdk/technitium the client: one server, typed calls
sdk/technitium/technitiumtest a canned server for tests, which holds every request against the API document
sdk/apidoc, api-defs/ the vendored API document and its reader
lib/servers the named servers one process works on
tools/ the MCP tools
cli/ the commands and settings
integration/, acceptance/ the live suites: the SDK, and the tools, against real servers
Tests

make test needs no server. The client is tested against a canned one that refuses any request the API document does not describe, and the tools end to end over an in-memory MCP session against two canned servers.

Everything else runs against real Technitium servers in Docker, because a canned server can only confirm what was already believed.

covers command
integration/ the sdk/technitium client: every method, against a real server make testacc-integration
acceptance/ the tools: every one of them, the journeys, and the built binary make testacc-acceptance

The live suites run on servers scripts/testenv.sh starts, and refuse any others. Each suite runs three times on the same servers, in order: one server (up single), a second started beside it (add), and the two made a cluster, which the suite does itself through sdk/technitium. A last pass then runs the tests that take the cluster apart - a node leaving, a secondary promoted, the cluster deleted - alone, since nothing else can run beside them. make testacc TOPOLOGIES=cluster goes straight to the cluster; TECHNITIUM_TEST_IMAGE=technitium/dns-server:15.5.0 make testacc runs another version. The script gives each server the Query Logs (Sqlite) app, which the log search reads, from the file the server's own app store names: fetched once and kept in .tools/cache. For the DHCP tests it also hands the suites a small image with a DHCP client in it (busybox), which they run on the servers' network for a moment as a machine asking for a lease; nothing outside that network hears it.

Each acceptance run records every tool it calls and fails if a registered tool was never seen to answer. The integration suite fails if a client method has no live test.

The journeys (acceptance/journey_*_test.go) chain the tools the way a session does and read the server back through the client after every write, because a tool's own answer is not proof: a first setup made from nothing with the tools alone, audited to nothing of its own, taken down again, and the server found holding exactly what it held before; a host moved to a new address with everything that pointed at it; every finding an audit can fix, fixed, audited again and put back; a zone's whole life from made to signed to deleted; a mistake undone from a backup; a token that may only look, held to that across every tool; an administrator's token without the write switches; many calls at once; every write done twice; every read leaving the servers unchanged; and two servers that differ brought into line.

acceptance/binary_test.go builds the real binary and speaks to it as a client does, which the rest never touches: serve over stdio saying nothing on stdout but the protocol, the flags registering what they say they do, the configuration file in the working directory read, serve --listen over HTTP with its bearer token, a start that cannot be made refused with the reason, and the info and tools commands.

Documentation

Overview

Package main implements technitium-mcp, an MCP server and CLI for running and auditing Technitium DNS servers.

Directories

Path Synopsis
Package apidefs holds the Technitium API document vendored beside it, and the list of the calls it describes that sdk/technitium does not wrap yet, for the tests that hold the client against them (see README.md here, and sdk/apidoc, which reads the document).
Package apidefs holds the Technitium API document vendored beside it, and the list of the calls it describes that sdk/technitium does not wrap yet, for the tests that hold the client against them (see README.md here, and sdk/apidoc, which reads the document).
Package cli implements the technitium-mcp command line interface: the cobra commands, flag and config handling, and the MCP server exposing Technitium DNS server tools to AI clients.
Package cli implements the technitium-mcp command line interface: the cobra commands, flag and config handling, and the MCP server exposing Technitium DNS server tools to AI clients.
lib
servers
Package servers is the set of Technitium servers one technitium-mcp process works on, each under a short name of the operator's choosing.
Package servers is the set of Technitium servers one technitium-mcp process works on, each under a short name of the operator's choosing.
testenv
Package testenv is what the two live suites share: the servers scripts/testenv.sh started for them, and which of the three ways technitium-mcp is used they stand for - one server, two that know nothing of each other, or two that are a cluster.
Package testenv is what the two live suites share: the servers scripts/testenv.sh started for them, and which of the three ways technitium-mcp is used they stand for - one server, two that know nothing of each other, or two that are a cluster.
sdk
apidoc
Package apidoc reads the Technitium API document vendored under api-defs: the calls it describes, by path, with the parameters each takes.
Package apidoc reads the Technitium API document vendored under api-defs: the calls it describes, by path, with the parameters each takes.
technitium
Package technitium is a client for the Technitium DNS Server HTTP API, the one its own web console uses.
Package technitium is a client for the Technitium DNS Server HTTP API, the one its own web console uses.
technitium/technitiumtest
Package technitiumtest is a canned Technitium server for tests: it answers the API calls a test tells it to and records what it was asked.
Package technitiumtest is a canned Technitium server for tests: it answers the API calls a test tells it to and records what it was asked.
Package tools defines the MCP tools exposed by technitium-mcp, split by the resource they act on (server.go, zones.go, ...).
Package tools defines the MCP tools exposed by technitium-mcp, split by the resource they act on (server.go, zones.go, ...).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL