AKADATA LIMITED

AKAMAN Command and MCP Usage

AKAMAN command-line usage, man-page options, examples, and an observed MCP stdio exchange.

AKAMAN

A small Linux C utility that retrieves the compact documentation fragment an AI agent needs from the host where it is running.

Download AKAMAN v0.1.0 source →

Command and MCP usage

The installed command is akaman. Its manual is akaman(1). The current binary does not provide a separate --help option: passing it prints the usage text and reports an invalid option (exit status 2).

Invocation forms

akaman QUERY [SECTION]: Look up a query, optionally narrowing to a manual section.
akaman grep akaman "ip link set" akaman -s 2 open
akaman -s SECTION QUERY: Select a manual section explicitly. A numeric section selects that manual section; an alphabetic value is a named section heading.
akaman -s 2 open akaman -s examples grep
akaman --source man|doc|headers QUERY: Explicitly choose a source.
akaman --source doc "sudo troubleshooting" akaman --source headers "sys/socket connect"
akaman --stats QUERY [SECTION]: Print the result followed by token metrics (page, full bytes, returned bytes, estimated tokens, reduction) on standard error.
akaman --stats "rsync --delete"
akaman --bench: Print the built-in benchmark table, then exit.
akaman --mcp: Run as an MCP stdio server: JSON-RPC over standard input and output, exposing the single man tool.
akaman --http[=ADDR] | --web[=ADDR]: Run as an HTTP JSON-RPC server. ADDR defaults to 127.0.0.1:8931 and requires APIKEY in the config file. --web is an alias for --http.
akaman --conf PATH: Read the configuration file from PATH instead of /etc/akaman/akamcp.conf.

Exit status

0: A result was produced.
1: The lookup failed (no match, missing page, or malformed webMCP configuration).
2: The command line was invalid (unknown option, missing query, or too many arguments).

A complete real example

An agent needs to know what gcc -fPIC means. The request and the result:

Agent needs to know what GCC -fPIC means
        ↓
MCP call:
man(query="gcc -fPIC")
        ↓
AKAMAN asks the host’s native documentation system
        ↓
AKAMAN locates gcc(1)
        ↓
AKAMAN extracts the matching -fPIC material
        ↓
Only that bounded fragment is returned
        ↓
Agent receives ~125 estimated tokens rather than
the ~366,562-token estimated full manual

The source was not compressed or rewritten. Irrelevant source material simply never entered the model context.

Observed MCP stdio exchange

Against the installed v0.1.0 binary, initialization reports akaman version 0.1.0; tool discovery returns exactly one tool, man; and a grep -r call returns the focused grep(1) option fragment.

initialize
  → serverInfo: akaman 0.1.0
  → protocolVersion: 2024-11-05
tools/list
  → man(query, section?, source?)
tools/call
  → man({"query":"grep -r"})
  → grep(1): -r, -R description

Real results from the installed binary

The samples below are unedited output from akaman v0.1.0 on this host. Each shows the command and the bounded fragment AKAMAN returns — never the whole manual.

$ akaman grep

grep(1)
SYNOPSIS
     grep [OPTION]... PATTERNS [FILE]...
     grep [OPTION]... -e PATTERNS ... [FILE]...
     grep [OPTION]... -f PATTERN_FILE ... [FILE]...

SECTIONS: NAME | SYNOPSIS | DESCRIPTION | OPTIONS | REGULAR EXPRESSIONS | EXIT STATUS | ENVIRONMENT | NOTES | COPYRIGHT | BUGS | Reporting Bugs | EXAMPLE | SEE ALSO

$ akaman "ip link set"

ip-link(8)
     ip link { set | change } { DEVICE | group GROUP }
             [ { up | down } ]
             [ type ETYPE TYPE_ARGS ]
             [ arp { on | off } ]
             [ dynamic { on | off } ]
             [ multicast { on | off } ]
             [ allmulticast { on | off } ]
             [ promisc { on | off } ]
             [ protodown { on | off } ]
             [ protodown_reason PREASON { on | off } ]
             [ trailers { on | off } ]
             [ txqueuelen PACKETS ]
             [ gso_max_size BYTES ] [ gso_ipv4_max_size BYTES ] [ gso_max_segs
             SEGMENTS ]
             [ gro_max_size BYTES ] [ gro_ipv4_max_size BYTES ]
             [ name NEWNAME ]
             [ address LLADDR ]
             [ broadcast LLADDR ]
             [ mtu MTU ]
             [ netns { PID | NETNSNAME | NETNSFILE } ]
             [ link-netnsid ID ]

$ akaman -s 2 open

open(2)
SYNOPSIS
     #include <fcntl.h>

     int open(const char *path, int flags, ...
                /* mode_t mode */ );

     int creat(const char *path, mode_t mode);

     int openat(int dirfd, const char *path, int flags, ...
                /* mode_t mode */ );

     /* Documented separately, in openat2(2): */
     int openat2(int dirfd, const char *path,
                const struct open_how *how, size_t size);

 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

     openat():
         Since glibc 2.10:
             _POSIX_C_SOURCE >= 200809L
         Before glibc 2.10:
             _ATFILE_SOURCE

SECTIONS: NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | STANDARDS | HISTORY | NOTES | BUGS | SEE ALSO

$ akaman "grep -r"

grep(1)
     -r, --recursive
            Read all files under each directory, recursively, following
            symbolic links only if they are on the command line.  Note that if
            no file operand is given, grep searches the working directory.
            This is equivalent to the -d recurse option.

     -R, --dereference-recursive
            Read all files under each directory, recursively.  Follow all
            symbolic links, unlike -r.

   Other Options

$ akaman --source headers "sys/socket connect"

#include <sys/socket.h>
   This function is a cancellation point and therefore not marked with
   __THROW.  */
extern int connect (int __fd, __CONST_SOCKADDR_ARG __addr, socklen_t __len);