1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242

.Dd October 26, 2025
.Dt VARLINK-MCP-BRIDGE 1
.Os
.Sh NAME
.Nm varlink-mcp-bridge
.Nd expose Varlink services as MCP (Model Context Protocol) tools
.Sh SYNOPSIS
.Nm
.Fl -varlink-address Ar address
.Fl -interface Ar name
.Op Fl -debug
.Sh DESCRIPTION
.Nm
connects to a Varlink service, introspects its interface definition, and exposes
all methods as MCP tools over stdio. This enables Claude Code to invoke Varlink
service methods directly as AI-available tools with automatic type translation
and documentation.
.Pp
The bridge handles the complete protocol translation:
.Bl -bullet -compact
.It
Varlink IDL types → JSON Schema (for MCP tool definitions)
.It
MCP tool calls → Varlink method invocations
.It
Varlink responses → MCP tool results
.El
.Pp
The following options are available:
.Bl -tag -width Ds
.It Fl -varlink-address Ar address
Varlink service address to connect to. Supports Unix domain sockets
.Pq Ic unix:/path/to/socket
or TCP addresses
.Pq Ic tcp:host:port .
Required.
.It Fl -interface Ar name
Varlink interface name to expose via MCP. Must match an interface provided by
the service at the given address. The interface name follows reverse-DNS notation
.Pq e.g., Ic de.profpatsch.ClaudeLastPosition .
Required.
.It Fl -debug
Enable verbose debug logging to stderr. Shows all JSON-RPC messages, Varlink
calls, and internal state transitions. Useful for troubleshooting bridge
configuration or service communication issues.
.El
.Sh MCP INTEGRATION
.Nm
is designed to be invoked by MCP clients (such as Claude Code) via the stdio
transport. It communicates using JSON-RPC 2.0 protocol and follows the MCP
specification.
.Ss Configuration
Create or edit
.Pa .mcp.json
in your project directory:
.Bd -literal -offset indent
{
  "mcpServers": {
    "my-service": {
      "command": "/path/to/varlink-mcp-bridge",
      "args": [
        "--varlink-address=unix:/run/user/1000/my.service.Socket",
        "--interface=my.service.Interface"
      ]
    }
  }
}
.Ed
.Pp
Multiple Varlink services can be exposed by adding additional entries to
.Ic mcpServers .
Each bridge instance connects to one interface.
.Ss Tool Naming
MCP tool names are taken directly from Varlink method names with no
transformation. For example:
.Bd -literal -offset indent
Interface: de.profpatsch.DisplayBrightness
Method: SetBrightnessAllMonitors
Tool name: SetBrightnessAllMonitors
.Ed
.Pp
This keeps tool names consistent with the original Varlink interface and
makes debugging easier since tool names match method names exactly
.Ss Documentation
Tool descriptions are extracted directly from Varlink interface documentation
comments
.Pq using Ic # syntax .
This makes MCP tools self-documenting and discoverable in Claude Code's tool
browser.
.Sh HOW IT WORKS
.Nm
performs the following operations on startup:
.Bl -enum
.It
Connects to the Varlink service at the specified address
.It
Calls
.Ic org.varlink.service.GetInterfaceDescription
to retrieve the interface definition
.It
Parses the Varlink IDL using the official IDL parser
.It
Translates each method signature into MCP tool schema with JSON Schema types
.It
Enters stdio loop, processing MCP JSON-RPC requests
.It
For each
.Ic tools/call
request, invokes the corresponding Varlink method
.It
Returns Varlink response data formatted as MCP tool result
.El
.Pp
Connections to the Varlink service are persistent and reused across multiple
tool invocations for efficiency.
.Sh TYPE MAPPING
Varlink types are translated to JSON Schema as follows:
.Bl -tag -width "TypeStruct" -compact
.It Ic bool
.Ic boolean
.It Ic int , Ic float
.Ic integer , number
.It Ic string
.Ic string
.It Ic []T
.Ic array
with items type T
.It Ic ?T
Optional type (not in required list)
.It Ic [string]T
.Ic object
with additionalProperties of type T
.It Ic (field: T, ...)
.Ic object
with typed properties
.El
.Sh EXAMPLES
.Ss Expose Edit Position Tracker
.Bd -literal -offset indent
$ varlink-mcp-bridge \\
    --varlink-address=unix:/run/user/1000/de.Profpatsch.ClaudeLastPosition \\
    --interface=de.profpatsch.ClaudeLastPosition
.Ed
.Pp
This exposes methods like
.Ic GetLastPosition
and
.Ic SetLastPosition
as MCP tools that Claude can invoke.
.Ss Expose Display Brightness Control
.Bd -literal -offset indent
$ varlink-mcp-bridge \\
    --varlink-address=unix:/run/user/1000/de.Profpatsch.DisplayBrightness \\
    --interface=de.profpatsch.DisplayBrightness
.Ed
.Ss Debug Mode
.Bd -literal -offset indent
$ varlink-mcp-bridge \\
    --varlink-address=unix:/run/user/1000/my.Service \\
    --interface=my.Service \\
    --debug 2>debug.log
.Ed
.Pp
Logs all protocol messages to
.Pa debug.log
for troubleshooting.
.Sh INSTALLATION
Build and install using Nix flakes:
.Bd -literal -offset indent
$ nix profile install git+https://codeberg.org/Profpatsch/Profpatsch?ref=canon#varlink-mcp-bridge
.Ed
.Pp
This installs
.Ic varlink-mcp-bridge
and the man page to your Nix profile.
.Sh ERROR HANDLING
.Nm
returns MCP error responses in the following cases:
.Bl -tag -width Ds
.It Parse Error Pq -32700
Invalid JSON received from MCP client
.It Invalid Request Pq -32600
Malformed JSON-RPC request (missing required fields, non-monotonic ID)
.It Method Not Found Pq -32601
Unknown MCP method (not
.Ic initialize , tools/list ,
or
.Ic tools/call )
.It Invalid Params Pq -32602
Unknown tool name or invalid tool arguments
.It Internal Error Pq -32603
Varlink call failed (connection error, unknown method, service error)
.El
.Pp
Error messages include detailed context to aid debugging, such as the actual
Varlink error returned by the service.
.Sh FILES
.Bl -tag -width Ds
.It Pa .mcp.json
MCP server configuration file specifying which Varlink services to expose
.It Pa /run/user/<uid>/*
Common location for user-specific Varlink service Unix sockets
.El
.Sh EXIT STATUS
.Ex -std
.Pp
The bridge runs indefinitely as an MCP server until the client closes stdin
or sends a termination signal.
.Sh SEE ALSO
.Xr varlink 7
.Pp
Varlink Protocol:
.Lk https://varlink.org
.Pp
Model Context Protocol:
.Lk https://modelcontextprotocol.io
.Pp
Claude Code Documentation:
.Lk https://docs.claude.com/claude-code
.Sh AUTHORS
.An Profpatsch
.Pp
.Nm
was created with
.An Claude Code .
.Sh CAVEATS
.Bl -bullet
.It
Only one Varlink interface can be exposed per bridge instance. Use multiple
.Pa .mcp.json
entries to expose multiple services.
.It
Varlink service must support persistent connections and handle multiple method
calls on the same socket.
.It
Documentation quality depends on the Varlink interface author including
.Ic #
comment annotations in the interface definition.
.It
Complex nested Varlink types may produce verbose JSON Schema that is less
readable in tool descriptions.
.El