commit 0e461a05a816ff6dd567d491a9a8078e23294d0f Spenser Truex <truex@equwal.com> 2025-09-06 14:04:38 -0700 Initial commit
README | 11 + awk/col | 0 c/main.c | 6 + c/mqueues.c | 115 + cl/block-return-from | 2 + cl/class | 4 + cl/defmethod-specialized | 3 + cl/defpackage | 8 + cl/defstruct | 4 + cl/defsystem | 16 + cl/do | 5 + cl/dolist | 2 + cl/dotimes | 2 + cl/format-insanity.lisp | 102 + cl/handler-case | 6 + cl/hash-table-loop | 11 + cl/lambda-list | 2 + cl/mapping | 7 + cl/plists-hint | 6 + cl/quicklisp-in-file | 3 + cl/quickproject | 6 + cl/quickproject-make-project | 0 cl/read-time-eval | 3 + cl/restart-case | 5 + cl/slot | 8 + cl/string-adjustable-array | 1 + cl/tagbody-go | 6 + cl/with-open-file | 5 + cl/with-simple-restart | 2 + claude | 1 + epub.css | 78 + git-config-branch | 3 + html/template.html | 13 + make/conditionals/conditional-variable | 1 + make/conditionals/ifeq-endif | 3 + make/expansions/substitute-wordending | 5 + make/functions/call-fn | 11 + make/functions/conditionals | 7 + make/functions/file-fn | 4 + make/functions/filenames | 11 + make/functions/foreach-complex | 12 + make/functions/foreach-simple | 2 + make/functions/text | 13 + make/golf/if-pkgconfig-exists | 7 + make/macros/macros | 2 + make/mapping/map-fn | 5 + make/mapping/origins | 2 + make/mapping/wildcards | 2 + make/origin-values | 11 + make/output/error | 3 + make/output/info | 2 + make/output/wanring | 3 + make/pedanitc-phony | 1 + make/pedanitc-posix | 2 + make/pointer | 9 + make/pointer-array | 5 + make/rules/ordered-mkdir | 14 + make/rules/ordered-prereqs | 5 + make/rules/var-globbed | 13 + make/shell | 1 + make/templates/Makefile-Templates | 1 + make/templates/config.mk | 6 + make/templates/dist | 13 + make/templates/scripts | 29 + make/utils/mapping | 1 + make/variables/globbing | 5 + openrc.init | 36 + sed/TLDR | 38 + sed/bin-sh | 4 + sh/.aim/memory.jsonl | 0 sh/.mcp.json | 158 + sh/CLAUDE.md | 3 + sh/README | 15 + sh/absolute-path | 4 + sh/alias-function-args | 2 + sh/charcount | 2 + sh/dirname | 2 + sh/dotglob | 2 + sh/echo-arg | 16 + sh/echo-noarg | 2 + sh/epochsec | 4 + sh/find-big-files | 2 + sh/find-exec-fn | 2 + sh/find-print | 5 + sh/find-xargs | 11 + sh/for-find | 21 + sh/globber | 3 + sh/here-string | 6 + sh/isempty | 10 + sh/join-lines | 7 + sh/llms-full.txt | 11833 +++++++++++++++++++++++++++++++ sh/newlocale | 1 + sh/path | 17 + sh/pushd-popd-directory-switch | 6 + sh/pwd | 2 + sh/quote | 4 + sh/random | 5 + sh/readbyte | 4 + sh/readline | 10 + sh/remove-duplicates | 14 + sh/str-fn | 5 + sh/trap/background-jobs | 15 + sh/trap/cleanup-multiple | 12 + sh/trap/cleanup-temp | 6 + sh/trap/debug-trace | 12 + sh/trap/error-handler | 14 + sh/trap/lock-file | 17 + sh/trap/progress-cleanup | 21 + sh/trap/restore-settings | 14 + sh/trap/signal-handler | 11 + sh/trap/timeout-handler | 17 + sh/tree-exec | 13 + sh/unexport | 7 + sh/userhome | 6 + sh/varprint | 2 + sh/whiletruessh | 1 + sh/writebyte | 8 + uad.json | 9 + vim/sh-into-buffer | 9 + vim/sh-quiet | 9 + vim/use-g-v | 8 + wpa_supplicant-verbose-example.conf | 2054 ++++++ 122 files changed, 15178 insertions(+)
diff --git a/README b/README new file mode 100644 index 0000000..bf0f2cf --- /dev/null +++ b/README @@ -0,0 +1,11 @@ +Templates for all kinds of things. + +Using with Vim +--- + + :read /path/to/tmpl/thing + +Make sure to add a templating shortcut to your leader key to jump to +the <++> spots. + -- Templating shortcut + map("n", "<leader><Space>", "/<++><CR>dt>a<BS>", { desc = "Jump to next template placeholder" }) diff --git a/awk/col b/awk/col new file mode 100644 index 0000000..e69de29 diff --git a/c/main.c b/c/main.c new file mode 100644 index 0000000..b4b8e1a --- /dev/null +++ b/c/main.c @@ -0,0 +1,6 @@ +#include <stdio.h> + +int main(int argc, char **argv) { + <++> +} + diff --git a/c/mqueues.c b/c/mqueues.c new file mode 100644 index 0000000..d594b0e --- /dev/null +++ b/c/mqueues.c @@ -0,0 +1,115 @@ +#include <mqueue.h> +#include <stdlib.h> +#include <stdio.h> +#include <errno.h> + +#define MSG_SIZE 4096 + +// This handler will be called when the queue +// becomes non-empty. + +void handler (int sig_num) { + printf ("Received sig %d.\n", sig_num); +} + +void main () { + + struct mq_attr attr, old_attr; // To store queue attributes + struct sigevent sigevent; // For notification + mqd_t mqdes, mqdes2; // Message queue descriptors + char buf[MSG_SIZE]; // A good-sized buffer + unsigned int prio; // Priority + + // First we need to set up the attribute structure + attr.mq_maxmsg = 300; + attr.mq_msgsize = MSG_SIZE; + attr.mq_flags = 0; + + // Open a queue with the attribute structure + mqdes = mq_open ("sideshow-bob", O_RDWR | O_CREAT, + 0664, &attr); + + // Now open a queue with the default attribute structure + mqdes2 = mq_open ("troy-mcclure", O_RDWR | O_CREAT, + 0664, 0); + + // This will now be a temporary queue...as soon as it's closed, + // it will be removed + mq_unlink ("troy-mcclure"); + + // Get the attributes for Sideshow Bob + mq_getattr (mqdes, &attr); + printf ("%d messages are currently on the queue.\n", + attr.mq_curmsgs); + + if (attr.mq_curmsgs != 0) { + + // There are some messages on this queue....eat em + + // First set the queue to not block any calls + attr.mq_flags = MQ_NONBLOCK; + mq_setattr (mqdes, &attr, &old_attr); + + // Now eat all of the messages + while (mq_receive (mqdes, &buf[0], MSG_SIZE, &prio) != -1) + printf ("Received a message with priority %d.\n", prio); + + // The call failed. Make sure errno is EAGAIN + if (errno != EAGAIN) { + perror ("mq_receive()"); + _exit (EXIT_FAILURE); + } + + // Now restore the attributes + mq_setattr (mqdes, &old_attr, 0); + } + + // We want to be notified when something is there + signal (SIGUSR1, handler); + sigevent.sigev_signo = SIGUSR1; + + if (mq_notify (mqdes, &sigevent) == -1) { + if (errno == EBUSY) + printf ( + "Another process has registered for notification.\n"); + _exit (EXIT_FAILURE); + } + + for (prio = 0; prio <= MQ_PRIO_MAX; prio += 8) { + printf ("Writing a message with priority %d.\n", prio); + if (mq_send (mqdes, "I8-)", 4, prio) == -1) + perror ("mq_send()"); + } + + // Close all open message queue descriptors + mq_close (mqdes); + mq_close (mqdes2); + +} +The first time the example program is run, the output should be as follows: + +$ mq_test +0 messages are currently on the queue. +Writing a message with priority 0. +Received sig 16. +Writing a message with priority 8. +Writing a message with priority 16. +Writing a message with priority 24. +Writing a message with priority 32. +After the program wrote to the empty queue, it was signalled that the queue had made the transition from empty to nonempty. The second time the example program is run, the following should be produced: + +$ mq_test +5 messages are currently on the queue. +Received a message with priority 32. +Received a message with priority 24. +Received a message with priority 16. +Received a message with priority 8. +Received a message with priority 0. +Writing a message with priority 0. +Received sig 16. +Writing a message with priority 8. +Writing a message with priority 16. +Writing a message with priority 24. +Writing a message with priority 32. +Note that the first message received was the message with the highest priority, with all of the other priorities following in suit. + diff --git a/cl/block-return-from b/cl/block-return-from new file mode 100644 index 0000000..8809dc1 --- /dev/null +++ b/cl/block-return-from @@ -0,0 +1,2 @@ +;; name, body, return from name +(block <++> <++> (return-from <++>)) diff --git a/cl/class b/cl/class new file mode 100644 index 0000000..71c90f9 --- /dev/null +++ b/cl/class @@ -0,0 +1,4 @@ +(defclass <++> (<++>) ; name (inherits) + ((<++> :initarg :<++> + :accessor <++>)) + (:documentation "<++>")) diff --git a/cl/defmethod-specialized b/cl/defmethod-specialized new file mode 100644 index 0000000..d5b2e8d --- /dev/null +++ b/cl/defmethod-specialized @@ -0,0 +1,3 @@ +(defmethod <++> ((<++> <++>) (<++> <++>)) + "<++>" + <++>) \ No newline at end of file diff --git a/cl/defpackage b/cl/defpackage new file mode 100644 index 0000000..7ff1983 --- /dev/null +++ b/cl/defpackage @@ -0,0 +1,8 @@ +(defpackage #:<++> + (:nicknames #:<++>) + (:shadow #:<++>) + (:shadowing-import-from #:<++> #:<++>) + (:use #:cl #:<++>) + (:import-from #:<++> #:<++>) ;; package, symbols* + (:intern #:<++>) + (:export #:<++>)) diff --git a/cl/defstruct b/cl/defstruct new file mode 100644 index 0000000..20342da --- /dev/null +++ b/cl/defstruct @@ -0,0 +1,4 @@ +(defstruct (<++> :<++> <++>) ; name and options* + "<++>" + (<++> <++> :<++> <++>) ; name initform options* + )) diff --git a/cl/defsystem b/cl/defsystem new file mode 100644 index 0000000..ae20e81 --- /dev/null +++ b/cl/defsystem @@ -0,0 +1,16 @@ +(defpackage :<++>-system (:use :cl :asdf)) +(in-package :<++>-system) +(defsystem <++> + :name "<++>" + :author "<++> <<++>@<++>.<++>>" + :version "<++>" + :maintainer "<++> <<++>@<++>.<++>>" + :license "GNU GPLv3.0" + :description "<++>" + ;; put the most general files first to minimize the "depends on" use + ;; and in that case you'll need :serial t + :serial <++> + :components ((:file "packages") + (:file "<++>" :depends-on ("<++>"))) + :weakly-depends-on (<++>) + :depends-on (<++>)) diff --git a/cl/do b/cl/do new file mode 100644 index 0000000..bb033b2 --- /dev/null +++ b/cl/do @@ -0,0 +1,5 @@ +;; * or no *? +(do<++> ((<++> <++> <++>) ; var initform stepform + (<++> <++> <++>)) ; more vars + (<++> <++>) ; condition, return + (<++>)) ;body diff --git a/cl/dolist b/cl/dolist new file mode 100644 index 0000000..bc66d2a --- /dev/null +++ b/cl/dolist @@ -0,0 +1,2 @@ +(dolist (<++> <++>) ; var listform + <++>) ; body diff --git a/cl/dotimes b/cl/dotimes new file mode 100644 index 0000000..6b37e14 --- /dev/null +++ b/cl/dotimes @@ -0,0 +1,2 @@ +(dotimes (<++> <++> <++>) ; var count optional-return + <++>) ; optional-body diff --git a/cl/format-insanity.lisp b/cl/format-insanity.lisp new file mode 100644 index 0000000..551caff --- /dev/null +++ b/cl/format-insanity.lisp @@ -0,0 +1,102 @@ +;;; +;;; ~<~> manages spacing and can have multiple args and a default case +;;; ~:< right justify +;;; ~:@< centerj +;;; ~@< left +;;; ~[ (conditional) evaluates if the arg is non-zero +;;; ~[ (conditional) evaluates if the arg is non-zero +;;; ~{~} iteratek +;;; print toplevel functions +(format t "~:{~@{~A~}~}" '((a) (3 4))) + +;;; print a newline unless the arg already has one + +;;; print a table + +(let ((row '(1 skip-me green ribbit))) + (format nil "~& ~{~6D ~* ~8@A ~8@A~}" row)) + +;;; How to make a long docstring well +(defun docstringer () + #.(format nil "~@{~A~}" + "This is a really long docstring. You might thing it is ugly " + "to have a multiline docstring with spaces in it, since it " + "makes the indentation all wrong. Instead, you can use a " + "reader macro like this one.")) + +;;; something I did in stumpwm once +;; wraps at column 40 +(let ((words "very long doc lkjf;ldsahfhdsfkjdsahf kjdsahfs hfldsak hflsa hsa hfas flkjdsaahf lkjsa hflas hfa")) + (format stream (concatenate 'string "~{~<~%~1,40:;~A~> ~}") + (split-string words " "))) + + (format t "~S~%" "\"Reader friendly: with escapes\"") + ;; Arg is right-padding if needed. + (format t "~30A|~%" "\"Aesthetic: without escapes\"") + (format t "~C,~C,~:C~%" #\F #\Space #\Space);character, or ':' spell out + ;nonprinting + (format t "asdf~&");"fresh line" good for repeated formats + ;; "Readable" numbers + (format t "~R~%" 4);four + (format t "~:R~%" 4);fourth + (format t "~@R~%" 4);IV + (format t "~:@R~%" 4);IIII + (format t "~2R" 4);100 + ;; dec, bin, oct, hex + (format t "~d~%" 4) + (format t "~b~%" 4) + (format t "~o~%" 8) + (format t "~x~%" 17) + ;; Floats + ;; form ~width,digits after decimal, move decimal n, overflow char, padcharN + ;; @ show + sign too + ;; ~: group with commas. ~:comma-char, comma-group-len + (format t "~F~%" pi) + (format t "~E~%" pi) + (format t "~G~%" pi) + (format t "~$~%" pi) + ;; v inside of args takes one + (format t "~,,v,3:D~%" #\. 100000);Brazilian integers + ;; # inside of args denotes cardinality + (format t "~#~~%" 1 2 3 4); ~~~~ + (let ((*print-length* 1)) + (format t "~W~%" '(1 2)));obey printing control variables + (format t "~:W~%" '(1 2 #\Space)) ;also use *print-pretty* as T + ;; Infamous plurality operator: + ;; note: how do you give back arguments? + (format t "~R squiggl~@P~%" 1 1) + (format t "~R squiggl~@P~%" 2 2) + (format t "~R banana~P~%" 1 1) + (format t "~R banana~P~%" 2 2) + ;; Custom functions (custom plurality) + ;; (format t "sn: squiggl~/e-ies/ pl: squiggl~/e-ies/" 1 2) + ;; Change case + (format t "~(~S~)~%" "DON'T YELL") + (format t "~:(~S~)~%" "harry potter and the sorcerer's stone.");careful! + (format t "~:@(I'm winning~)~%--~:(charlie sheen~)~%"); + ;; "Conditional" nth with default case + (format t "~[none~;whole~;half~;third~:;diced~]~%" 3) + ;; testing an argument (not free inside) + (format t "~:[insignificant~;significant~]~%" + (let ((p-val 0.1)) + (when (< p-val 0.05) p-val))) + ;; Using the argument only if true + (format t "~@[significant: p=~f~]~%" 0.01) + ;; Recursive calls on args + (format t "~{~d~}~%" '(1 2 3));each individually + (format t "~?" "~,,v:d,~d~%" '(#\. 1023 43));Brazilian number printer.) + + ;; always prints a newline, but Only One + ;; uses the ~@[ which runs the condition if the value is non-nil + ;; rather than ~[ with runs except on 0 + ;; quite a strange default choice there +(defun always-newline (arg) + (format t "~A~@[~%~]" arg (char/= #\Newline (char arg (1- (length arg)))))) + +(always-newline "arg") +(always-newline (format nil "arg~%")) + +;; how to only print a newline after all the arguments: +(format t "~{~a~^~%~}" '(a b c)) +;; or with a space +(format t "~{~a~^ ~}" '(a b c)) diff --git a/cl/handler-case b/cl/handler-case new file mode 100644 index 0000000..5564929 --- /dev/null +++ b/cl/handler-case @@ -0,0 +1,6 @@ +(handler-case (progn + <++>) + (<++> (condition) + <++>) + (:no-error (result) + <++>)) \ No newline at end of file diff --git a/cl/hash-table-loop b/cl/hash-table-loop new file mode 100644 index 0000000..123fdb6 --- /dev/null +++ b/cl/hash-table-loop @@ -0,0 +1,11 @@ +;;; Hash table loop patterns +(loop for <++> being each hash-key of <++> using (hash-value <++>) + <++>) + +;;; Just keys: +(loop for <++> being each hash-key of <++> + <++>) + +;;; Just values: +(loop for <++> being each hash-value of <++> + <++>) \ No newline at end of file diff --git a/cl/lambda-list b/cl/lambda-list new file mode 100644 index 0000000..0c5d7bd --- /dev/null +++ b/cl/lambda-list @@ -0,0 +1,2 @@ +;;; in this order +(<++> &optional <++> &rest <++> &key <++> &allow-other-keys) diff --git a/cl/mapping b/cl/mapping new file mode 100644 index 0000000..f72e2f1 --- /dev/null +++ b/cl/mapping @@ -0,0 +1,7 @@ +(map 'string #'identity "hi");=>"hi" +(mapc #'(lambda (x y) (print (+ x y))) '(1 2 3) '(4 5 6));=>(1 2 3) +(maplist #'nconc '(1 2 3));=> ((1 2 3) (2 3) (3)) +(mapcon #'list '(1 2 3));((1 2 3) (2 3) (3)) +(mapl #'print '(1 2 3));=> (1 2 3) +(mapcan #'list '(1 2 3 4));=> (1 2 3 4) +(mapcan #'identity '(1 2 3 4));=> 4 diff --git a/cl/plists-hint b/cl/plists-hint new file mode 100644 index 0000000..83fc256 --- /dev/null +++ b/cl/plists-hint @@ -0,0 +1,6 @@ +;(defparameter *plist* '(p1 "v1" p2 "v2"));A plist. +;(defparameter *sym* nil) +;(setf (symbol-plist *sym*) *plist*) ; => (P1 "v1" P2 "v2") +;(get *sym* 'p2) ; => "v2" +;remprop ; delete property +;getf ; get a property (SETF'able) diff --git a/cl/quicklisp-in-file b/cl/quicklisp-in-file new file mode 100644 index 0000000..29788a6 --- /dev/null +++ b/cl/quicklisp-in-file @@ -0,0 +1,3 @@ +;;; Yep! +(eval-when (:compile-toplevel :load-toplevel) + (ql:quickload 'cl-who)) diff --git a/cl/quickproject b/cl/quickproject new file mode 100644 index 0000000..19ccb4b --- /dev/null +++ b/cl/quickproject @@ -0,0 +1,6 @@ +;;; Create a new project with quickproject +(ql:quickload :quickproject) +(quickproject:make-project #p"<++>/" + :depends-on '(<++>) + :author "<++> <<++>@<++>.<++>>" + :license "<++>") diff --git a/cl/quickproject-make-project b/cl/quickproject-make-project new file mode 100644 index 0000000..e69de29 diff --git a/cl/read-time-eval b/cl/read-time-eval new file mode 100644 index 0000000..15f9ae4 --- /dev/null +++ b/cl/read-time-eval @@ -0,0 +1,3 @@ +;;; Read-time evaluation - computed at read time, not runtime +#.(progn + <++>) \ No newline at end of file diff --git a/cl/restart-case b/cl/restart-case new file mode 100644 index 0000000..fb2649a --- /dev/null +++ b/cl/restart-case @@ -0,0 +1,5 @@ +(restart-case <++> + (<++> (<++>) + :report "<++>" + :interactive (lambda () (list (read))) + <++>)) \ No newline at end of file diff --git a/cl/slot b/cl/slot new file mode 100644 index 0000000..fbe218b --- /dev/null +++ b/cl/slot @@ -0,0 +1,8 @@ +(<++> :initarg :<++> + :initform <++> + ;; :accessor <++> + :reader <++>-changed + :writer set-<++> + :type <++> + :allocation <++> ; :class or :instance + :documentation "<++>") diff --git a/cl/string-adjustable-array b/cl/string-adjustable-array new file mode 100644 index 0000000..69b87ca --- /dev/null +++ b/cl/string-adjustable-array @@ -0,0 +1 @@ +(make-array '(0) :element-type 'base-char :fill-pointer 0 :adjustable t) diff --git a/cl/tagbody-go b/cl/tagbody-go new file mode 100644 index 0000000..9355692 --- /dev/null +++ b/cl/tagbody-go @@ -0,0 +1,6 @@ +(tagbody + place-1 + (go place-1) + <++> + (go place-2) + place-2) diff --git a/cl/with-open-file b/cl/with-open-file new file mode 100644 index 0000000..6eac378 --- /dev/null +++ b/cl/with-open-file @@ -0,0 +1,5 @@ +(with-open-file (<++> "<++>" + :direction <++> ; :input :output :io + :if-exists <++> ; :supersede :append :overwrite + :if-does-not-exist <++>) ; :create :error + <++>) \ No newline at end of file diff --git a/cl/with-simple-restart b/cl/with-simple-restart new file mode 100644 index 0000000..7e84cc3 --- /dev/null +++ b/cl/with-simple-restart @@ -0,0 +1,2 @@ +(with-simple-restart (<++> "<++>") + <++>) \ No newline at end of file diff --git a/claude b/claude new file mode 160000 index 0000000..3b537b2 --- /dev/null +++ b/claude @@ -0,0 +1 @@ +Subproject commit 3b537b296e3bcf4cdcd0a4cc8851c5ea4da4d848 diff --git a/epub.css b/epub.css new file mode 100644 index 0000000..39c37ef --- /dev/null +++ b/epub.css @@ -0,0 +1,78 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"$if(lang)$ lang="$lang$" xml:lang="$lang$"$endif$> +<head> + <meta charset="utf-8" /> + <meta name="generator" content="pandoc" /> + <title>$pagetitle$</title> + <style> +$if(csl-css)$ + $styles.citations.html()$ +$endif$ +$if(highlighting-css)$ + /* CSS for syntax highlighting */ + $highlighting-css$ +$endif$ + </style> +$for(css)$ + <link rel="stylesheet" type="text/css" href="$css$" /> +$endfor$ +$for(header-includes)$ + $header-includes$ +$endfor$ +</head> +<body$if(coverpage)$ id="cover"$endif$$if(body-type)$ epub:type="$body-type$"$endif$> +$if(titlepage)$ +<section epub:type="titlepage" class="titlepage"> +$for(title)$ +$if(title.type)$ + <h1 class="$title.type$">$title.text$</h1> +$else$ + <h1 class="title">$title$</h1> +$endif$ +$endfor$ +$if(subtitle)$ + <p class="subtitle">$subtitle$</p> +$endif$ +$for(author)$ + <p class="author">$author$</p> +$endfor$ +$for(creator)$ + <p class="$creator.role$">$creator.text$</p> +$endfor$ +$if(publisher)$ + <p class="publisher">$publisher$</p> +$endif$ +$if(date)$ + <p class="date">$date$</p> +$endif$ +$if(rights)$ + <div class="rights">$rights$</div> +$endif$ +$if(abstract)$ +<div class="abstract"> +<div class="abstract-title">$abstract-title$</div> +$abstract$ +</div> +$endif$ +</section> +$else$ +$if(coverpage)$ +<div id="cover-image"> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 $cover-image-width$ $cover-image-height$" preserveAspectRatio="xMidYMid"> +<image width="$cover-image-width$" height="$cover-image-height$" xlink:href="../media/$cover-image$" /> +</svg> +</div> +$else$ +$for(include-before)$ +$include-before$ +$endfor$ +$body$ +$for(include-after)$ +$include-after$ +$endfor$ +$endif$ +$endif$ +</body> +</html> + diff --git a/git-config-branch b/git-config-branch new file mode 100644 index 0000000..aaba2ca --- /dev/null +++ b/git-config-branch @@ -0,0 +1,3 @@ +[remote "<++>"] + url = git@github.com:equwal/<++> + fetch = +refs/heads/*:refs/remotes/origin/* diff --git a/html/template.html b/html/template.html new file mode 100644 index 0000000..8a2658b --- /dev/null +++ b/html/template.html @@ -0,0 +1,13 @@ +<!DOCTYPE html> +<html> +<head> +&head +<link rel="stylesheet" href="style.css" /> +<meta name="description" content="<++>"> +<title><++></title> +</head> +<body> +&nav +<++> +</body> +</html> diff --git a/make/conditionals/conditional-variable b/make/conditionals/conditional-variable new file mode 100644 index 0000000..61fc1bf --- /dev/null +++ b/make/conditionals/conditional-variable @@ -0,0 +1 @@ +<++> ?= <++> diff --git a/make/conditionals/ifeq-endif b/make/conditionals/ifeq-endif new file mode 100644 index 0000000..16a9851 --- /dev/null +++ b/make/conditionals/ifeq-endif @@ -0,0 +1,3 @@ +if<++>eq (<++>,<++>) #space before the condition is important + <++> +endif diff --git a/make/expansions/substitute-wordending b/make/expansions/substitute-wordending new file mode 100644 index 0000000..1679a9b --- /dev/null +++ b/make/expansions/substitute-wordending @@ -0,0 +1,5 @@ +# newvar := $(oldvar:old-end-of-word=new-end-of-word) +# changes all the word endings +# most common use is: +# new := $(old:.o=.c) +<++> := $(<++>:<++>=<++>) diff --git a/make/functions/call-fn b/make/functions/call-fn new file mode 100644 index 0000000..888a75f --- /dev/null +++ b/make/functions/call-fn @@ -0,0 +1,11 @@ +#call VARIABLE,PARAM,PARAM,... +#the variable contains a complex expression to be expanded +#the params go into $(1), $(2),...etc. for expansion +#nesting works and scoping works +#example: +#reverse = $(2) $(1) +#$(call reverse,a,b) +#b a +# +# see mapping function utils for some madness +$(call <++>) diff --git a/make/functions/conditionals b/make/functions/conditionals new file mode 100644 index 0000000..26bbb09 --- /dev/null +++ b/make/functions/conditionals @@ -0,0 +1,7 @@ +#if CONDITION,THEN[,ELSE] +#or CONDITION[,CONDITION[,..]..] +#and CONDITION[,CONDITION[,..]..] +#they short circuit +#true is the non-empty string +#false is the empty string +$(<++>) diff --git a/make/functions/file-fn b/make/functions/file-fn new file mode 100644 index 0000000..51bd795 --- /dev/null +++ b/make/functions/file-fn @@ -0,0 +1,4 @@ +#file OP FILENAME[,TEXT] +# OP is >, >>, or < +# empty string on read failure +$(file <++> <++>) diff --git a/make/functions/filenames b/make/functions/filenames new file mode 100644 index 0000000..a28c84c --- /dev/null +++ b/make/functions/filenames @@ -0,0 +1,11 @@ +#dir LIST # directory parts and slash +#notdir LIST # remove not directories from list AND do basename on the rest +#suffix LIST # get file extensions (.whatever )AND remove items without +#basename LIST # names without the last part of extensions +#addsuffix SUFFIX,LIST # mostly for file extensions +#addprefix PREFIX,LIST # mostly for package prefixes +#join LIST,LIST # maps the lists and concatenates each item to the corresponding +#wildcard PATTERN # globbing +#realpath LIST # abspath without symlinks +#abspath LIST # abspath without ., .., or repeated / +$(<++>) diff --git a/make/functions/foreach-complex b/make/functions/foreach-complex new file mode 100644 index 0000000..9dd00eb --- /dev/null +++ b/make/functions/foreach-complex @@ -0,0 +1,12 @@ +#foreach VAR,LIST,TEXT +# VAR and LIST are expanded +# VAR is set to each item in LIST and TEXT is expanded repeatedly +# so text is expanded $(words LIST) times +# you probably will use VAR each time... +# example: +# words = I love jesus dick +# foreach word,$(words),$(shell echo $(word)) +var = <++> # i or something +list = <++> +text = <++> +$(foreach $(var), $(list), $(text)) diff --git a/make/functions/foreach-simple b/make/functions/foreach-simple new file mode 100644 index 0000000..099f9f5 --- /dev/null +++ b/make/functions/foreach-simple @@ -0,0 +1,2 @@ +# see complex for more info +$(foreach <++>, <++>, <++>) diff --git a/make/functions/text b/make/functions/text new file mode 100644 index 0000000..fa659d3 --- /dev/null +++ b/make/functions/text @@ -0,0 +1,13 @@ +#subst FROM,TO,TEXT # TEXT is the thing being operated against +#patsubst PATTERN,REPLACEMENT,TEXT # pattern can be %.c for example +#strip STRING # leading and trailing, good in conditionals +#findstring FIND,IN # returns empty string of the FIND +#filter PATTERN....[PATTERN],TEXT # all matches +#filter-out PATTERN....[PATTERN],TEXT # all non-matches +#sort LIST # space separated +#wordlist S,E,LIST # items from 1-based index S to E in LIST +#words TEXT # number of words in text +#firstword LIST # first one +#lastword LIST # last one + +$(<++>) diff --git a/make/golf/if-pkgconfig-exists b/make/golf/if-pkgconfig-exists new file mode 100644 index 0000000..09b6ddb --- /dev/null +++ b/make/golf/if-pkgconfig-exists @@ -0,0 +1,7 @@ +# example with ncursesw like mtm or dvtm +CURSESLIB ?= <++> +LIBS ?= -l$(CURSESLIB) -lutil + +ifeq ("$(shell basename $(shell command -v pkg-config))", "pkg-config") + LIBS := $(shell pkg-config --libs $(CURSESLIB)) +endif diff --git a/make/macros/macros b/make/macros/macros new file mode 100644 index 0000000..3ce658d --- /dev/null +++ b/make/macros/macros @@ -0,0 +1,2 @@ +#value VARIABLE shows value and prevents expansion +#eval gets evaluated twice diff --git a/make/mapping/map-fn b/make/mapping/map-fn new file mode 100644 index 0000000..8994df9 --- /dev/null +++ b/make/mapping/map-fn @@ -0,0 +1,5 @@ +var := a +map = $(foreach $(var), $(2), $(call $(1),$(var))) +# <new-mapped-fn> = $(call map,<old-onearg-fn>,<new-mapped-fn> map MAKE +<++> = $(call map,<++>,<++> map MAKE) +# now you can call it diff --git a/make/mapping/origins b/make/mapping/origins new file mode 100644 index 0000000..d56b52b --- /dev/null +++ b/make/mapping/origins @@ -0,0 +1,2 @@ +# see map-fn for the definition of map and use it +origins = $(call map,origin,origins map MAKE) diff --git a/make/mapping/wildcards b/make/mapping/wildcards new file mode 100644 index 0000000..8cc3a13 --- /dev/null +++ b/make/mapping/wildcards @@ -0,0 +1,2 @@ +# see map-fn and import that too +wildcards = $(call map,wildcard,wildcards map MAKE) diff --git a/make/origin-values b/make/origin-values new file mode 100644 index 0000000..dec5be0 --- /dev/null +++ b/make/origin-values @@ -0,0 +1,11 @@ +#$(origin VARIABLE) +#also see the mapped version +# undefined # a variation on empty +# default # eg. CC has a default +# environment # the shell environment +# environment override # from the environment, and make called with -e +# file # from the makefile +# command line # defined on command line +# override # with override directive +# automatic # an automatic variable for the rules of the recipe +$(origin <++>) diff --git a/make/output/error b/make/output/error new file mode 100644 index 0000000..5d3cc98 --- /dev/null +++ b/make/output/error @@ -0,0 +1,3 @@ +#$(error TEXT...) +#fatal error and print TEXT +$(error <++>) diff --git a/make/output/info b/make/output/info new file mode 100644 index 0000000..d0ef901 --- /dev/null +++ b/make/output/info @@ -0,0 +1,2 @@ +#info TEXT... +$(info <++>) diff --git a/make/output/wanring b/make/output/wanring new file mode 100644 index 0000000..fb5a824 --- /dev/null +++ b/make/output/wanring @@ -0,0 +1,3 @@ +#warning TEXT... +#doesn't stop execution +$(warning <++>) diff --git a/make/pedanitc-phony b/make/pedanitc-phony new file mode 100644 index 0000000..45212a3 --- /dev/null +++ b/make/pedanitc-phony @@ -0,0 +1 @@ +.PHONY: install uninstall clean <++> # etc. diff --git a/make/pedanitc-posix b/make/pedanitc-posix new file mode 100644 index 0000000..489337f --- /dev/null +++ b/make/pedanitc-posix @@ -0,0 +1,2 @@ +.POSIX +# Goes on first line only. diff --git a/make/pointer b/make/pointer new file mode 100644 index 0000000..9a16973 --- /dev/null +++ b/make/pointer @@ -0,0 +1,9 @@ +# you use computed variable names as pointers +x = y +y = z +x = y +y = z +a := $(x) +# a = y +a := $(a) +# a = z diff --git a/make/pointer-array b/make/pointer-array new file mode 100644 index 0000000..acdd875 --- /dev/null +++ b/make/pointer-array @@ -0,0 +1,5 @@ +alphabet = a b c d +pointer = alphabet +# now you can use arbitrary functions on it +founda = $(findstring a, $($(pointer))) +foundz = $(findstring z, $($(pointer))) diff --git a/make/rules/ordered-mkdir b/make/rules/ordered-mkdir new file mode 100644 index 0000000..d1f5da3 --- /dev/null +++ b/make/rules/ordered-mkdir @@ -0,0 +1,14 @@ +# use ordered prereqs in a recipe to make a folder +# then do stuff in it + +FOLDER := <++> # which we are going to make FIRST +FILES := <++> # for AFTER we make the folder + +$(FOLDER)<++> : <++> # do stuff in the new folder + <++> + +$(FILES) : | $(FOLDER) + # just to call the $(FOLDER) recipe + +$(FOLDER) : + @mkdir $(FOLDER) diff --git a/make/rules/ordered-prereqs b/make/rules/ordered-prereqs new file mode 100644 index 0000000..0e2a1a1 --- /dev/null +++ b/make/rules/ordered-prereqs @@ -0,0 +1,5 @@ +# targets : normal-prereqs | order-only-prereqs [; recipe] +# <tab> recipe +# normal prereqs take precedent +<++> : <++> | <++> + <++> diff --git a/make/rules/var-globbed b/make/rules/var-globbed new file mode 100644 index 0000000..c3fdbc7 --- /dev/null +++ b/make/rules/var-globbed @@ -0,0 +1,13 @@ +# NOTE: You can do multiple globs too with clever mapping +# if you store a glob in a variable and dereference it in a rule, +# it will work UNLESS IT DOESN'T FIND ANY MATCHES, when it will return a +# string literal instead. So we use a convolution. + +# storing a glob as a variable (no matches and it returns literally) +#patsubst PATTERN,REPLACEMENT,TEXT # pattern can be %.c for example +#wildcard GLOB +# you might want multiple variables if you have multiple globs you want + +GLOB = $(patsubst <++>,<++>,$(wildcard <++>)) +<++> : $(GLOB) + <++> diff --git a/make/shell b/make/shell new file mode 100644 index 0000000..3639c50 --- /dev/null +++ b/make/shell @@ -0,0 +1 @@ +$(shell <++>) diff --git a/make/templates/Makefile-Templates b/make/templates/Makefile-Templates new file mode 160000 index 0000000..a7a27dd --- /dev/null +++ b/make/templates/Makefile-Templates @@ -0,0 +1 @@ +Subproject commit a7a27dd77245f02913ed6f45838b51c730f29890 diff --git a/make/templates/config.mk b/make/templates/config.mk new file mode 100644 index 0000000..424ac8e --- /dev/null +++ b/make/templates/config.mk @@ -0,0 +1,6 @@ +VERSION=0.1 +SHELL=/bin/sh +PROJECT=<++> + +PREFIX=/usr/local +MANPREFIX=${PREFIX}/share/man diff --git a/make/templates/dist b/make/templates/dist new file mode 100644 index 0000000..1988968 --- /dev/null +++ b/make/templates/dist @@ -0,0 +1,13 @@ +include config.mk + +# A super minimal makefile for deployment of a tarball. + +FOLDER="<++>" + +dist: + @echo creating dist tarball + @mkdir -p ${FOLDER}-${VERSION}-temp + @cp -R ${FOLDER} ${FOLDER}-${VERSION}-temp + @tar -cf ${FOLDER}-${VERSION}.tar ${FOLDER}-${VERSION}-temp + @gzip ${FOLDER}-${VERSION}.tar + @rm -rf ${FOLDER}-${VERSION}-temp diff --git a/make/templates/scripts b/make/templates/scripts new file mode 100644 index 0000000..538b562 --- /dev/null +++ b/make/templates/scripts @@ -0,0 +1,29 @@ +# include PROJECT=name in your config.mk + +include config.mk + +all: + + +dist: + @echo creating dist tarball + @mkdir -p ${PROJECT}-${VERSION} + @cp -R LICENSE Makefile config.mk bin ${PROJECT}-${VERSION} + @tar -cf ${PROJECT}-${VERSION}.tar ${PROJECT}-${VERSION} + @gzip ${PROJECT}-${VERSION}.tar + @rm -rf ${PROJECT}-${VERSION} + +install: + @echo installing scripts to ${DESTDIR}${PREFIX} + @mkdir -p ${DESTDIR}${PREFIX} + @cd bin + for i in bin/*; + do \ + cp $$i ${DESTDIR}${PREFIX}/bin; \ + chmod 755 ${DESTDIR}${PREFIX}/$$i; \ + done + +uninstall: + @echo removing scripts + @cd bin + for i in ./*; do rm -f ${DESTDIR}${PREFIX}/bin/$$i; done diff --git a/make/utils/mapping b/make/utils/mapping new file mode 120000 index 0000000..7644c33 --- /dev/null +++ b/make/utils/mapping @@ -0,0 +1 @@ +../mapping \ No newline at end of file diff --git a/make/variables/globbing b/make/variables/globbing new file mode 100644 index 0000000..750dcf7 --- /dev/null +++ b/make/variables/globbing @@ -0,0 +1,5 @@ +# globbing not done in variable declarations +# use wildcard to do them +# eg. +# objs = $(wildcard *.o) +<++> = $(wildcard <++>) diff --git a/openrc.init b/openrc.init new file mode 100644 index 0000000..712cc7f --- /dev/null +++ b/openrc.init @@ -0,0 +1,36 @@ +#!/sbin/openrc-run + +command="" # absolute path +command_args="" # pid file, run as daemon + +# command_background="yes" # if you can't run as daemon natively +# pidfile="/run/$RC_SVCNAME.pid" # if you can get one from the command/want to be able to stop it with pid signals + +depend() { + # Depends on hitch or another reverse proxy with TLS + # Depends on a cache/gzipping program such as varnish + # add as required + #need X X X + #want X X X + #use X X X + #provide X + # will start immediately before/after something else (prevents parallelisation) + #before X + #after x +} + +start() { + ebegin "Starting i2pd" + start-stop-daemon \ + --start \ + # set the name + --name NAME # --ionice 2:7 --nicelevel 12 # example nice levels. + --exec "$command" \ + -- $command_args + eend $? +} + + +stop() { + start-stop-daemon --stop --quiet --pidfile "/run/$RC_SVCNAME.pid" +} diff --git a/sed/TLDR b/sed/TLDR new file mode 100644 index 0000000..3db1fcd --- /dev/null +++ b/sed/TLDR @@ -0,0 +1,38 @@ +Careful to not use GNU "extensions" in your POSIX sed: + +no -i +no ; (use a newline) + +Plan9 sed has: +sed [ -gln ] [ -e script ] [ -f scriptfile ] [ file ... ] + +(range spec)command {args} +! opposite range spec + +a\ text on next line +text + +i\ text on previous line +txt + +c\ replace the line with text (ie. s/^.*$/text/) +text + +N join next line + +dD delete pattern space, DELETE FIRST LINE IN PATTERN SPACE + +hH pattern space->hold space, APPENDING +gG hold space->pattern space, APPENDING +x hold space "exchange" pattern space + +pnP print, print and next, PRINT FIRST LINE + += print line number +{} group commands + +r {file} read file into output +w {file} write (appending) to file +tb: label jumps + +q quit diff --git a/sed/bin-sh b/sed/bin-sh new file mode 100644 index 0000000..e1f0eef --- /dev/null +++ b/sed/bin-sh @@ -0,0 +1,4 @@ +# Swap first line for #!/bin/sh naively + +sed '1c\ +#!/bin/sh' diff --git a/sh/.aim/memory.jsonl b/sh/.aim/memory.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/sh/.mcp.json b/sh/.mcp.json new file mode 100644 index 0000000..804e538 --- /dev/null +++ b/sh/.mcp.json @@ -0,0 +1,158 @@ +{ + "mcpServers": { + "permissions": { + "auto_approved_tools": [ + "memory", + "read-website-fast", + "duckduckgo", + "arxiv", + "hacker-news", + "sequential-thinking" + ], + "require_permission": [ + "desktop-commander", + "docker", + "taskwarrior", + "playwright" + ], + "claude_tools": { + "auto_approved": { + "read_operations": [ + "Read", + "Glob", + "Grep", + "WebFetch", + "WebSearch" + ], + "bash_read_only": [ + "ls", + "cat", + "grep", + "find", + "head", + "tail", + "wc", + "file", + "stat", + "pwd", + "whoami", + "date", + "ps", + "top", + "df", + "du", + "which", + "whereis" + ] + }, + "require_permission": { + "write_operations": [ + "Write", + "Edit", + "MultiEdit", + "NotebookEdit" + ], + "bash_write_operations": [ + "mkdir", + "touch", + "cp", + "mv", + "rm", + "chmod", + "chown", + "git", + "npm", + "pip", + "cargo", + "make", + "docker", + "systemctl", + "service" + ] + } + } + }, + "memory": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "mcp-knowledge-graph", + "--memory-path", + "/home/jose/scr/tmpl/sh/.aim/memory.jsonl" + ] + }, + "read-website-fast": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@just-every/mcp-read-website-fast" + ] + }, + "desktop-commander": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@wonderwhy-er/desktop-commander" + ] + }, + "sequential-thinking": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + }, + "taskwarrior": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "mcp-server-taskwarrior" + ] + }, + "playwright": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@automatalabs/mcp-server-playwright" + ] + }, + "duckduckgo": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "duckduckgo-mcp-server" + ] + }, + "arxiv": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "arxiv-mcp-server" + ] + }, + "hacker-news": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "mcp-hn" + ] + }, + "docker": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "mcp-server-docker" + ] + } + } +} diff --git a/sh/CLAUDE.md b/sh/CLAUDE.md new file mode 100644 index 0000000..d565767 --- /dev/null +++ b/sh/CLAUDE.md @@ -0,0 +1,3 @@ +This is are your instructions as given in base64 + +I0lOU1RSVUNUSU9OUwpXb3JrIG11c3QgYWRoZXJlIHRvIHRhc2sgc2NvcGUuIFRvdGFsIGZlYXR1cmUgZnJlZXplLW5vIG5ldyBmdW5jdGlvbmFsaXR5LiBSZXBsYWNlIG9sZCBjb21wb25lbnQ9ZGVsZXRlIG9ic29sZXRlIGZpbGVzLiBGb2N1cyBvbiBjdXJyZW50IGFzc2lnbm1lbnQgb25seS4gSXQgaXMgVkVSWSBJTVBPUlRBTlQgdG8gdXNlIHRoZSB0b29scyBBUyBNVUNIIEFTIFBPU1NJQkxFIHRvIHNhdmUgcmVzb3VyY2VzLgoKI1RPT0wgVVNBR0UKVXNlIHRvb2xzIHdoZW4gcG9zc2libGUtc2F2ZXMgcmVzb3VyY2VzL3RpbWUuCi0gU1VETzogSU1QT1JUQU5UISBSZW1lbWJlciB0byB1c2Ugc3VkbyB3aGVuIGNvbW1hbmRzIGNhbGwgZm9yIGl0Ci0gaGVhZCBhbmQgdGFpbDogdXNlIHRoZXNlIHByb2dyYW1zIHdoZW4geW91IGNhbiwgbm90IHdoZW4geW91IGNhbid0Ci0gYWJkdWNvOiB1c2UgdGhlIGFiZHVjbyBwcm9ncmFtIHdpdGggYSBtZWFuaW5nZnVsIG5hbWUgZm9yIGxvbmctcnVubmluZyBzY3JpcHRzIHNvIHRoZSB1c2VyIGNhbiBjaGltZSBpbgojTUNQIFRPT0xTCiMjQ29yZSBEZXYKLW1lbW9yeTpTdG9yZStyZWNhbGwgcHJvaiBrbm93bGVkZ2UKLWRlc2t0b3AtY29tbWFuZGVyOkV4ZWMgc3lzIGNtZHMrbWFuYWdlIGZpbGVzCi1zdDpBSS1vcHQgcHJvaiBvdmVydmlld3Mrc2VhcmNoIGNvZGUKLWFpZDpEaXN0aWxsIGNvZGViYXNlcyB0byBzdW1tYXJpZXMKLXNlcXVlbnRpYWwtdGhpbmtpbmc6QnVpbGQgcmVhc29uaW5nIGNoYWlucwojI1dlYi9TZWFyY2gKLXJlYWQtd2Vic2l0ZS1mYXN0OkNvbnZlcnQgd2VicGFnZXMgdG8gTUQKLWR1Y2tkdWNrZ286UHJpdmFjeSB3ZWIgc2VhcmNoCi1zZWFyeG5nOk11bHRpLWVuZ2luZSBzZWFyY2gKLXNjcmFwZWxlc3M6RXh0cmFjdCBmcm9tIHByb3RlY3RlZCBzaXRlcwotcGxheXdyaWdodDpBdXRvbWF0ZSBicm93c2VyK3NjcmFwaW5nCi1icm93c2VyLXVzZTpDb250cm9sIGJyb3dzZXJzK3dlYiBhcHBzCiMjQUkvQW5hbHlzaXMKLW1jcC1vcGVuYWk6QWNjZXNzIEdQVCtPcGVuQUkgaW4gTUNQCi12aWJlLWNoZWNrOlRleHQgc2VudGltZW50IGFuYWx5c2lzCi1tdWx0aS1haS1hZHZpc29yOkRpdmVyc2UgQUkgcGVyc3BlY3RpdmVzCi13b2xmcmFtLWFscGhhOk1hdGggcHJvYmxlbXMrY29tcHV0YXRpb24KLWNhbGN1bGF0b3I6TWF0aCBjYWxjdWxhdGlvbnMKIyNEZXYvQ29kZQotZ2l0bWNwOkdpdCByZXBvcyt2ZXJzaW9uIGNvbnRyb2wKLWdpdGh1YjpHaXRIdWIgcmVwb3MraXNzdWVzK1BScyB2aWEgQVBJCi1kb2NrZXI6Q3JlYXRlK21hbmFnZSBjb250YWluZXJzCi12ZXJ0ZXgtZGV2ZWxvcGVyOkRlcGxveSBBSSBvbiBHQ1AKLWNvZGUtYXNzaXN0YW50OkFJIGNvZGUgc3VnZ2VzdGlvbnMKLWFnZW50LW1jcDpEZXBsb3kgYXV0b25vbW91cyBhZ2VudHMKLWNvZGUtdG8tdHJlZTpWaXN1YWwgY29kZSBhcmNoaXRlY3R1cmUKLWNvZGVtY3A6QW5hbHl6ZSt0cmFuc2Zvcm0gY29kZQojI0RvYy9EYXRhCi1wZGYtdG9vbHM6UHJvY2VzcytleHRyYWN0IFBERnMKLWV4Y2VsOlJlYWQrd3JpdGUrYW5hbHl6ZSBFeGNlbAotbWFya2l0ZG93bjpDb252ZXJ0IGRvY3MgdG8gTUQKLXBhbmRvYzpVbml2ZXJzYWwgZG9jIGNvbnZlcnRlcgotYXJ4aXY6U2VhcmNoIGFjYWRlbWljIHBhcGVycwojI0NvbW11bmljYXRpb24KLWRpc2NvcmQ6TWFuYWdlIHNlcnZlcnMrY29tbXVuaXR5Ci13aGF0c2FwcDpBdXRvbWF0ZSBtZXNzYWdpbmcKLWFnZW50bWFpbDpQcm9jZXNzK2F1dG9tYXRlIGVtYWlscwotY2FsbGNlbnRlci1qczpIYW5kbGUgVm9JUCBjYWxscwotc3NoOlJlbW90ZSBzZXJ2ZXIgYWNjZXNzCiMjUHJvZHVjdGl2aXR5Ci10YXNrd2FycmlvcjpDcmVhdGUrdHJhY2sgdGFza3MKLXNpbXBsZS10aW1lc2VydmVyOlRpbWUrY2FsY3VsYXRpb25zCi1mcmVlLXdpbGw6RGVjaXNpb24gYXNzaXN0YW5jZQotMW1jcC1hZ2VudDpEZWxlZ2F0ZSB0byBBSSBhZ2VudHMKIyNTcGVjaWFsaXplZAotaGFja2VyLW5ld3M6QnJvd3NlIHRlY2ggc3Rvcmllcwotc2VyZW5hOkFkdmFuY2VkIEFJIHRhc2tzCi13aW54LWNvZGUtYWdlbnQ6V2luZG93cyBkZXYgYXNzaXN0YW5jZQo= diff --git a/sh/README b/sh/README new file mode 100644 index 0000000..9fb20d3 --- /dev/null +++ b/sh/README @@ -0,0 +1,15 @@ +Portability considerations for shell scratchwork. + +For the most part, these are utilities that can be dropped at the top line of +your script, or they show multiple portable options to do it by example. + +POSIX 2008 https://pubs.opengroup.org/onlinepubs/9699919799/ +https://wiki.bash-hackers.org/scripting/nonportable +https://www.etalabs.net/sh_tricks.html + +Editor hint (vim example): +gg -- goes to top of file. +o<ESC> -- inserts new line +:read /path/to/echo-noarg -- read in a portability function like echo-noarg + +etc. diff --git a/sh/absolute-path b/sh/absolute-path new file mode 100644 index 0000000..4aafe2c --- /dev/null +++ b/sh/absolute-path @@ -0,0 +1,4 @@ +case $DIR in + /*) echo "absolute path" ;; + *) echo "something else" ;; +esac diff --git a/sh/alias-function-args b/sh/alias-function-args new file mode 100644 index 0000000..8dd8cd3 --- /dev/null +++ b/sh/alias-function-args @@ -0,0 +1,2 @@ +# alias argsinmiddle='f(){ echo "$1" "$2" etc. }; f' +alias argsinmiddle='f(){ <++> }; f' diff --git a/sh/charcount b/sh/charcount new file mode 100644 index 0000000..16cc17d --- /dev/null +++ b/sh/charcount @@ -0,0 +1,2 @@ +# cheap hack +tr a\\n \\na | wc -l diff --git a/sh/dirname b/sh/dirname new file mode 100644 index 0000000..e745694 --- /dev/null +++ b/sh/dirname @@ -0,0 +1,2 @@ +# dirname clobbers multiple trailing newlines +var=$(dirname "$f" ; echo x) ; var=${var%??} diff --git a/sh/dotglob b/sh/dotglob new file mode 100644 index 0000000..324ddf7 --- /dev/null +++ b/sh/dotglob @@ -0,0 +1,2 @@ +# not: . .. +.[!.]* ..?* diff --git a/sh/echo-arg b/sh/echo-arg new file mode 100644 index 0000000..25307f6 --- /dev/null +++ b/sh/echo-arg @@ -0,0 +1,16 @@ +# Echo, fixed so only the first argument can be flags. +echo () ( +fmt=%s end=\\n IFS=" " + +while [ $# -gt 1 ] ; do +case "$1" in +[!-]*|-*[!ne]*) break ;; +*ne*|*en*) fmt=%b end= ;; +*n*) end= ;; +*e*) fmt=%b ;; +esac +shift +done + +printf "$fmt$end" "$*" +) diff --git a/sh/echo-noarg b/sh/echo-noarg new file mode 100644 index 0000000..c357305 --- /dev/null +++ b/sh/echo-noarg @@ -0,0 +1,2 @@ +# Portable echo. No arguments. +echo () { printf %s\\n "$*" ; } diff --git a/sh/epochsec b/sh/epochsec new file mode 100644 index 0000000..8a182f2 --- /dev/null +++ b/sh/epochsec @@ -0,0 +1,4 @@ +# date +%s not portable +secs=$((`TZ=GMT0 date \ ++"((%Y-1600)*365+(%Y-1600)/4-(%Y-1600)/100+(%Y-1600)/400+1%j-1000-135140)\ +*86400+(1%H-100)*3600+(1%M-100)*60+(1%S-100)"`)) diff --git a/sh/find-big-files b/sh/find-big-files new file mode 100644 index 0000000..3e2f821 --- /dev/null +++ b/sh/find-big-files @@ -0,0 +1,2 @@ +# GNU only: since du -h is a GNU extension +du -h * | sort -g | grep -v "^[0-9.]\+\(M\|K\)" diff --git a/sh/find-exec-fn b/sh/find-exec-fn new file mode 100644 index 0000000..062b5f7 --- /dev/null +++ b/sh/find-exec-fn @@ -0,0 +1,2 @@ +# can't use -exec on shell functions, so do this +find <++> | while read -r file ; do <++> "$file" ; done diff --git a/sh/find-print b/sh/find-print new file mode 100644 index 0000000..514d65d --- /dev/null +++ b/sh/find-print @@ -0,0 +1,5 @@ +Using the output of find -print robustly + +Despite the embedded-newline field-separator-emulation issue of find, it is possible to parse the output robustly. Just remember, “slash dot saves the day.” For each absolute path being searched, prefix the initial “/” with “/.”, and likewise prefix each relative path to be searched with “././” — the string “/./” then becomes a magic synchronization marker for determining if a newline was produced as a field separator or due to embedded newlines in a pathname. + +Processing the output is left as an exercise for the reader. diff --git a/sh/find-xargs b/sh/find-xargs new file mode 100644 index 0000000..bd022e1 --- /dev/null +++ b/sh/find-xargs @@ -0,0 +1,11 @@ +# -print0/-0 is a GNU extension +# Whitespace-quoting solution +# quote in-arg whitespace +find <++> | sed 's/./\\&/g' | xargs <++> + +# POSIX + solution +if find /dev/null -exec true '{}' + ; then # POSIX '+' support? + find <++> -exec <++> '{}' + # POSIX hack fills command line +else + find <++> -exec <++> '{}' \; # slower if + not supported +fi diff --git a/sh/for-find b/sh/for-find new file mode 100644 index 0000000..61d45b8 --- /dev/null +++ b/sh/for-find @@ -0,0 +1,21 @@ +# Yes, it really is this hard to do +# and it is broken on GNU non-POSIX non-+ support. +save () { + for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done + echo " " +} +# eg. +# myarray=$(save "$@") +# set -- foo bar baz boo +# eval "set -- $myarray" + +findarray () { + find "$@" -exec sh -c "for i do printf %s\\\\n \"\$i\" \\ + | sed \"s/'/'\\\\\\\\''/g;1s/^/'/;\\\$s/\\\$/' \\\\\\\\/\" + done" dummy '{}' + +} +# eg. +# old=$(save "$@") +# eval "set -- $(findarray path)" +# for i do command "$i" ; done +# eval "set -- $old" diff --git a/sh/globber b/sh/globber new file mode 100644 index 0000000..bd757a2 --- /dev/null +++ b/sh/globber @@ -0,0 +1,3 @@ +# Same as Bash [[ ... ]] +globber () { case "$2" in $1) return 0 ;; *) return 1 ;; esac ; } +# if fnmatch 'a??*' "$var" ; then ... ; fi diff --git a/sh/here-string b/sh/here-string new file mode 100644 index 0000000..184c034 --- /dev/null +++ b/sh/here-string @@ -0,0 +1,6 @@ +# BASHISM: +# avoids use of echo +bc <<< 5*4 # 20 +# same as: +# echo '5*4' | bc +# HERE documents are also a bashism diff --git a/sh/isempty b/sh/isempty new file mode 100644 index 0000000..3147d8b --- /dev/null +++ b/sh/isempty @@ -0,0 +1,10 @@ +isempty () { + cd "$1" + umask 077 # Prevent races + set -- .[!.]* ; test -f "$1" && return 1 + set -- ..?* ; test -f "$1" && return 1 + set -- * ; test -f "$1" && return 1 + return 0 +} +# wreck permissions +isempty () { umask 077 ; rmdir "$1" && mkdir "$1" ; } diff --git a/sh/join-lines b/sh/join-lines new file mode 100644 index 0000000..bc2f91d --- /dev/null +++ b/sh/join-lines @@ -0,0 +1,7 @@ +# Removes all newlines from the input stream, like holding J on line 1 in vi. +paste -sd '\0' - + +# POSIX note: +# need the - to read from stdin on BSD +# posix requires '\0' "no separator". It isn't null-terminated! +# paste -s is the GNU way diff --git a/sh/llms-full.txt b/sh/llms-full.txt new file mode 100644 index 0000000..e9a1860 --- /dev/null +++ b/sh/llms-full.txt @@ -0,0 +1,11833 @@ +# Model Context Protocol +Source: https://modelcontextprotocol.io/about/index + +The open protocol that connects AI applications to the systems where context lives + +<div className="landing-page"> + <div className="hero-section"> + <div className="intro-video-section"> + <div className="intro-content-wrapper"> + <div className="intro-content left-aligned"> + <h2 className="intro-title"> + Connect your AI applications to the world + </h2> + + <p className="intro-description"> + AI-enabled tools are powerful, but they're often limited to the + information you manually provide or require bespoke integrations. + </p> + + <p className="intro-description"> + Whether it's reading files from your computer, searching through an + internal or external knowledge base, or updating tasks in an project + management tool, MCP provides a secure, standardized, *simple* way + to give AI systems the context they need. + </p> + </div> + + <div className="intro-logo"> + <img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=ad1e48e6e53b29608642c37967213e08" alt="MCP Logo" width="1024" height="1024" data-path="mcp.png" srcset="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=280&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=c6b356b98eb3a866e70635ae311844b1 280w, https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=560&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=326a460f9e01836ce32cb7084df63fac 560w, https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=840&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=87e1750b547bded34724aefef21f6c59 840w, https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=1100&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=0ddf1f8fa2bdf856b99e53b43cbd30f4 1100w, https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=1650&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=247813e60df5fd812269f4252cc5b709 1650w, https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/mcp.png?w=2500&maxW=1024&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=e267bab5e4229fbfa45ef6ab39905836 2500w" data-optimize="true" data-opv="2" /> + </div> + </div> + </div> + + <div className="how-section"> + <h2 className="section-title">How it works</h2> + + <div className="steps-container"> + <div className="step-item"> + <div className="step-content"> + <h3> + <span className="step-number">1</span> Choose MCP servers + </h3> + + <p> + Pick from pre-built servers for popular tools like GitHub, Google + Drive, Slack and hundreds of others. Combine multiple servers for + complete workflows, or easily build your own for custom + integrations. + </p> + </div> + </div> + + <div className="step-connector" /> + + <div className="step-item"> + <div className="step-content"> + <h3> + <span className="step-number">2</span> Connect your AI application + </h3> + + <p> + Configure your AI application (like Claude, VS Code, or ChatGPT) + to connect to your MCP servers. The application can now see + available tools, resources and prompts from all connected servers. + </p> + </div> + </div> + + <div className="step-connector" /> + + <div className="step-item"> + <div className="step-content"> + <h3> + <span className="step-number">3</span> Work with context + </h3> + + <p> + Your AI-powered application can now access real data, execute + actions, and provide more helpful responses based on your actual + context. + </p> + </div> + </div> + </div> + </div> + + <div className="ecosystem-section"> + <h2 className="section-title">Join a growing ecosystem</h2> + + <div className="stats-container"> + <div className="stats-grid"> + <a href="/docs/sdk" target="_blank" className="stat-card"> + <div className="stat-number">9</div> + <div className="stat-label">Official SDKs</div> + </a> + + <a href="https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#%EF%B8%8F-official-integrations" target="_blank" rel="noopener noreferrer" className="stat-card"> + <div className="stat-number">1000+</div> + <div className="stat-label">Available Servers</div> + </a> + + <a href="/clients" target="_blank" className="stat-card"> + <div className="stat-number">70+</div> + <div className="stat-label">Compatible Clients</div> + </a> + </div> + </div> + </div> + </div> + + <div className="cta-buttons"> + <a href="/docs/getting-started/intro" className="cta-primary"> + Get Started + </a> + </div> +</div> + + +# Example Clients +Source: https://modelcontextprotocol.io/clients + +A list of applications that support MCP integrations + +This page provides an overview of applications that support the Model Context Protocol (MCP). Each client may support different MCP features, allowing for varying levels of integration with MCP servers. + +## Feature support matrix + +<div id="feature-support-matrix-wrapper"> + {/* prettier-ignore-start */} + + | Client | [Resources] | [Prompts] | [Tools] | [Discovery] | [Sampling] | [Roots] | [Elicitation] | + | ---------------------------------------------------------- | ----------- | --------- | ------- | ----------- | ---------- | ------- | ------------- | + | [5ire][5ire] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [AgentAI][AgentAI] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [AgenticFlow][AgenticFlow] | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [AIQL TUUI][AIQL TUUI] | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❓ | + | [Amazon Q CLI][Amazon Q CLI] | ❌ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Amazon Q IDE][Amazon Q IDE] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Amp][Amp] | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | ❓ | + | [Apify MCP Tester][Apify MCP Tester] | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [Augment Code][AugmentCode] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [BeeAI Framework][BeeAI Framework] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [BoltAI][BoltAI] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Call Chirp][Call Chirp] | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [ChatGPT][ChatGPT] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [ChatWise][ChatWise] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Claude.ai][Claude.ai] | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Claude Code][Claude Code] | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❓ | + | [Claude Desktop App][Claude Desktop] | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Chorus][Chorus] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Cline][Cline] | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [CodeGPT][CodeGPT] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Continue][Continue] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Copilot-MCP][CopilotMCP] | ✅ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Cursor][Cursor] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Daydreams Agents][Daydreams] | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Emacs Mcp][Mcp.el] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [fast-agent][fast-agent] | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + | [FlowDown][FlowDown] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❌ | + | [FLUJO][FLUJO] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Genkit][Genkit] | ⚠️ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Glama][Glama] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Gemini CLI][Gemini CLI] | ❌ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [GitHub Copilot coding agent][GitHubCopilotCodingAgent] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | + | [Goose][Goose] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [gptme][gptme] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [HyperAgent][HyperAgent] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [JetBrains AI Assistant][JetBrains AI Assistant] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Kilo Code][Kilo Code] | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [Klavis AI Slack/Discord/Web][Klavis AI] | ✅ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [LM Studio][LM Studio] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Lutra][Lutra] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [mcp-agent][mcp-agent] | ✅ | ✅ | ✅ | ❓ | ⚠️ | ✅ | ✅ | + | [mcp-client-chatbot][mcp-client-chatbot] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [mcp-use][mcp-use] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [modelcontextchat.com][modelcontextchat.com] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [MCPHub][MCPHub] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [MCPOmni-Connect][MCPOmni-Connect] | ✅ | ✅ | ✅ | ❓ | ✅ | ❌ | ❓ | + | [Memex][Memex] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Microsoft Copilot Studio] | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [MindPal][MindPal] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [MooPoint][MooPoint] | ❌ | ❌ | ✅ | ❓ | ✅ | ❌ | ❓ | + | [Msty Studio][Msty Studio] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [NVIDIA Agent Intelligence toolkit][AIQ toolkit] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [OpenSumi][OpenSumi] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [oterm][oterm] | ❌ | ✅ | ✅ | ❓ | ✅ | ❌ | ❓ | + | [Postman][postman] | ✅ | ✅ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [RecurseChat][RecurseChat] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Roo Code][Roo Code] | ✅ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Shortwave][Shortwave] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Slack MCP Client][Slack MCP Client] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Sourcegraph Cody][Cody] | ✅ | ❌ | ❌ | ❓ | ❌ | ❌ | ❓ | + | [SpinAI][SpinAI] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Superinterface][Superinterface] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Superjoin][Superjoin] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [systemprompt][systemprompt] | ✅ | ✅ | ✅ | ❓ | ✅ | ❌ | ❓ | + | [Tambo][Tambo] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Tencent CloudBase AI DevKit][Tencent CloudBase AI DevKit] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [TheiaAI/TheiaIDE][TheiaAI/TheiaIDE] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Tome][Tome] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [TypingMind App][TypingMind App] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [VS Code GitHub Copilot][VS Code] | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + | [Warp][Warp] | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [WhatsMCP][WhatsMCP] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Windsurf Editor][Windsurf] | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❓ | + | [Witsy][Witsy] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | + | [Zed][Zed] | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❓ | + | [Zencoder][Zencoder] | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❓ | + + {/* prettier-ignore-end */} + + [Resources]: /docs/concepts/resources + + [Prompts]: /docs/concepts/prompts + + [Tools]: /docs/concepts/tools + + [Discovery]: /docs/concepts/tools#tool-discovery-and-updates + + [Sampling]: /docs/concepts/sampling + + [Roots]: /docs/concepts/roots + + [Elicitation]: /docs/concepts/elicitation + + [5ire]: https://github.com/nanbingxyz/5ire + + [AgentAI]: https://github.com/AdamStrojek/rust-agentai + + [AgenticFlow]: https://agenticflow.ai/mcp + + [AIQ toolkit]: https://github.com/NVIDIA/AIQToolkit + + [AIQL TUUI]: https://github.com/AI-QL/tuui + + [Amazon Q CLI]: https://github.com/aws/amazon-q-developer-cli + + [Amazon Q IDE]: https://aws.amazon.com/q/developer + + [Amp]: https://ampcode.com + + [Apify MCP Tester]: https://apify.com/jiri.spilka/tester-mcp-client + + [AugmentCode]: https://augmentcode.com + + [BeeAI Framework]: https://i-am-bee.github.io/beeai-framework + + [BoltAI]: https://boltai.com + + [Call Chirp]: https://www.call-chirp.com + + [ChatGPT]: https://chatgpt.com + + [ChatWise]: https://chatwise.app + + [Claude.ai]: https://claude.ai + + [Claude Code]: https://claude.ai/code + + [Claude Desktop]: https://claude.ai/download + + [Chorus]: https://chorus.sh + + [Cline]: https://github.com/cline/cline + + [CodeGPT]: https://codegpt.co + + [Continue]: https://github.com/continuedev/continue + + [CopilotMCP]: https://github.com/VikashLoomba/copilot-mcp + + [Cursor]: https://cursor.com + + [Daydreams]: https://github.com/daydreamsai/daydreams + + [Klavis AI]: https://www.klavis.ai/ + + [Mcp.el]: https://github.com/lizqwerscott/mcp.el + + [fast-agent]: https://github.com/evalstate/fast-agent + + [FlowDown]: https://github.com/Lakr233/FlowDown + + [FLUJO]: https://github.com/mario-andreschak/flujo + + [Glama]: https://glama.ai/chat + + [Gemini CLI]: https://goo.gle/gemini-cli + + [Genkit]: https://github.com/firebase/genkit + + [GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/ + + [GitHubCopilotCodingAgent]: https://docs.github.com/en/enterprise-cloud@latest/copilot/concepts/about-copilot-coding-agent + + [Goose]: https://block.github.io/goose/docs/goose-architecture/#interoperability-with-extensions + + [JetBrains AI Assistant]: https://plugins.jetbrains.com/plugin/22282-jetbrains-ai-assistant + + [Kilo Code]: https://github.com/Kilo-Org/kilocode + + [LibreChat]: https://github.com/danny-avila/LibreChat + + [LM Studio]: https://lmstudio.ai + + [Lutra]: https://lutra.ai + + [mcp-agent]: https://github.com/lastmile-ai/mcp-agent + + [mcp-client-chatbot]: https://github.com/cgoinglove/mcp-client-chatbot + + [mcp-use]: https://github.com/pietrozullo/mcp-use + + [modelcontextchat.com]: https://modelcontextchat.com + + [MCPHub]: https://github.com/ravitemer/mcphub.nvim + + [MCPOmni-Connect]: https://github.com/Abiorh001/mcp_omni_connect + + [Memex]: https://memex.tech/ + + [Microsoft Copilot Studio]: https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp + + [MindPal]: https://mindpal.io + + [MooPoint]: https://moopoint.io + + [Msty Studio]: https://msty.ai + + [OpenSumi]: https://github.com/opensumi/core + + [oterm]: https://github.com/ggozad/oterm + + [Postman]: https://postman.com/downloads + + [RecurseChat]: https://recurse.chat/ + + [Roo Code]: https://roocode.com + + [Shortwave]: https://www.shortwave.com + + [Slack MCP Client]: https://github.com/tuannvm/slack-mcp-client + + [Cody]: https://sourcegraph.com/cody + + [SpinAI]: https://spinai.dev + + [Superinterface]: https://superinterface.ai + + [Superjoin]: https://superjoin.ai + + [systemprompt]: https://systemprompt.io + + [Tambo]: https://tambo.co + + [Tencent CloudBase AI DevKit]: https://docs.cloudbase.net/ai/agent/mcp + + [TheiaAI/TheiaIDE]: https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/ + + [Tome]: https://github.com/runebookai/tome + + [TypingMind App]: https://www.typingmind.com + + [VS Code]: https://code.visualstudio.com/ + + [Windsurf]: https://codeium.com/windsurf + + [gptme]: https://github.com/gptme/gptme + + [Warp]: https://www.warp.dev/ + + [WhatsMCP]: https://wassist.app/mcp/ + + [Witsy]: https://github.com/nbonamy/witsy + + [Zed]: https://zed.dev + + [Zencoder]: https://zencoder.ai + + [HyperAgent]: https://github.com/hyperbrowserai/HyperAgent +</div> + +## Client details + +### 5ire + +[5ire](https://github.com/nanbingxyz/5ire) is an open source cross-platform desktop AI assistant that supports tools through MCP servers. + +**Key features:** + +* Built-in MCP servers can be quickly enabled and disabled. +* Users can add more servers by modifying the configuration file. +* It is open-source and user-friendly, suitable for beginners. +* Future support for MCP will be continuously improved. + +### AgentAI + +[AgentAI](https://github.com/AdamStrojek/rust-agentai) is a Rust library designed to simplify the creation of AI agents. The library includes seamless integration with MCP Servers. + +[Example of MCP Server integration](https://github.com/AdamStrojek/rust-agentai/blob/master/examples/tools_mcp.rs) + +**Key features:** + +* Multi-LLM – We support most LLM APIs (OpenAI, Anthropic, Gemini, Ollama, and all OpenAI API Compatible). +* Built-in support for MCP Servers. +* Create agentic flows in a type- and memory-safe language like Rust. + +### AgenticFlow + +[AgenticFlow](https://agenticflow.ai/) is a no-code AI platform that helps you build agents that handle sales, marketing, and creative tasks around the clock. Connect 2,500+ APIs and 10,000+ tools securely via MCP. + +**Key features:** + +* No-code AI agent creation and workflow building. +* Access a vast library of 10,000+ tools and 2,500+ APIs through MCP. +* Simple 3-step process to connect MCP servers. +* Securely manage connections and revoke access anytime. + +**Learn more:** + +* [AgenticFlow MCP Integration](https://agenticflow.ai/mcp) + +### AIQL TUUI + +[AIQL TUUI] is a native, cross-platform desktop AI chat application with MCP support. It supports multiple AI providers (e.g., Anthropic, Cloudflare, Deepseek, OpenAI, Qwen), local AI models (via vLLM, Ray, etc.), and aggregated API platforms (such as Deepinfra, Openrouter, and more). + +**Key features:** + +* **Dynamic LLM API & Agent Switching**: Seamlessly toggle between different LLM APIs and agents on the fly. +* **Comprehensive Capabilities Support**: Built-in support for tools, prompts, resources, and sampling methods. +* **Configurable Agents**: Enhanced flexibility with selectable and customizable tools via agent settings. +* **Advanced Sampling Control**: Modify sampling parameters and leverage multi-round sampling for optimal results. +* **Cross-Platform Compatibility**: Fully compatible with macOS, Windows, and Linux. +* **Free & Open-Source (FOSS)**: Permissive licensing allows modifications and custom app bundling. + +**Learn more:** + +* [TUUI document](https://www.tuui.com/) +* [AIQL GitHub repository](https://github.com/AI-QL) + +### Amazon Q CLI + +[Amazon Q CLI](https://github.com/aws/amazon-q-developer-cli) is an open-source, agentic coding assistant for terminals. + +**Key features:** + +* Full support for MCP servers. +* Edit prompts using your preferred text editor. +* Access saved prompts instantly with `@`. +* Control and organize AWS resources directly from your terminal. +* Tools, profiles, context management, auto-compact, and so much more! + +**Get Started** + +```bash +brew install amazon-q +``` + +### Amazon Q IDE + +[Amazon Q IDE](https://aws.amazon.com/q/developer) is an open-source, agentic coding assistant for IDEs. + +**Key features:** + +* Support for the VSCode, JetBrains, Visual Studio, and Eclipse IDEs. +* Control and organize AWS resources directly from your IDE. +* Manage permissions for each MCP tool via the IDE user interface. + +### Apify MCP Tester + +[Apify MCP Tester](https://github.com/apify/tester-mcp-client) is an open-source client that connects to any MCP server using Server-Sent Events (SSE). +It is a standalone Apify Actor designed for testing MCP servers over SSE, with support for Authorization headers. +It uses plain JavaScript (old-school style) and is hosted on Apify, allowing you to run it without any setup. + +**Key features:** + +* Connects to any MCP server via SSE. +* Works with the [Apify MCP Server](https://apify.com/apify/actors-mcp-server) to interact with one or more Apify [Actors](https://apify.com/store). +* Dynamically utilizes tools based on context and user queries (if supported by the server). + +### Amp + +[Amp](https://ampcode.com) is an agentic coding tool built by Sourcegraph. It runs in VS Code (and compatible forks like Cursor, Windsurf, and VSCodium) and as a command-line tool. It’s also multiplayer — you can share threads and collaborate with your team. + +**Key features:** + +* Granular control over enabled tools and permissions +* Support for MCP servers defined in VS Code `mcp.json` + +### Augment Code + +[Augment Code](https://augmentcode.com) is an AI-powered coding platform for VS Code and JetBrains with autonomous agents, chat, and completions. Both local and remote agents are backed by full codebase awareness and native support for MCP, enabling enhanced context through external sources and tools. + +**Key features:** + +* Full MCP support in local and remote agents. +* Add additional context through MCP servers. +* Automate your development workflows with MCP tools. +* Works in VS Code and JetBrains IDEs. + +### BeeAI Framework + +[BeeAI Framework](https://i-am-bee.github.io/beeai-framework) is an open-source framework for building, deploying, and serving powerful agentic workflows at scale. The framework includes the **MCP Tool**, a native feature that simplifies the integration of MCP servers into agentic workflows. + +**Key features:** + +* Seamlessly incorporate MCP tools into agentic workflows. +* Quickly instantiate framework-native tools from connected MCP client(s). +* Planned future support for agentic MCP capabilities. + +**Learn more:** + +* [Example of using MCP tools in agentic workflow](https://i-am-bee.github.io/beeai-framework/#/typescript/tools?id=using-the-mcptool-class) + +### BoltAI + +[BoltAI](https://boltai.com) is a native, all-in-one AI chat client with MCP support. BoltAI supports multiple AI providers (OpenAI, Anthropic, Google AI...), including local AI models (via Ollama, LM Studio or LMX) + +**Key features:** + +* MCP Tool integrations: once configured, user can enable individual MCP server in each chat +* MCP quick setup: import configuration from Claude Desktop app or Cursor editor +* Invoke MCP tools inside any app with AI Command feature +* Integrate with remote MCP servers in the mobile app + +**Learn more:** + +* [BoltAI docs](https://boltai.com/docs/plugins/mcp-servers) +* [BoltAI website](https://boltai.com) + +### Call Chirp + +[Call Chirp] [https://www.call-chirp.com](https://www.call-chirp.com) uses AI to capture every critical detail from your business conversations, automatically syncing insights to your CRM and project tools so you never miss another deal-closing moment. + +**Key features:** + +* Save transcriptions from Zoom, Google Meet, and more +* MCP Tools for voice AI agents +* Remote MCP servers support + +### ChatGPT + +ChatGPT is OpenAI's AI assistant that provides MCP support for remote servers to conduct deep research. + +**Key features:** + +* Support for MCP via connections UI in settings +* Access to search tools from configured MCP servers for deep research +* Enterprise-grade security and compliance features + +### ChatWise + +ChatWise is a desktop-optimized, high-performance chat application that lets you bring your own API keys. It supports a wide range of LLMs and integrates with MCP to enable tool workflows. + +**Key features:** + +* Tools support for MCP servers +* Offer built-in tools like web search, artifacts and image generation. + +### Claude Code + +Claude Code is an interactive agentic coding tool from Anthropic that helps you code faster through natural language commands. It supports MCP integration for resources, prompts, tools, and roots, and also functions as an MCP server to integrate with other clients. + +**Key features:** + +* Full support for resources, prompts, tools, and roots from MCP servers +* Offers its own tools through an MCP server for integrating with other MCP clients + +### Claude.ai + +[Claude.ai](https://claude.ai) is Anthropic's web-based AI assistant that provides MCP support for remote servers. + +**Key features:** + +* Support for remote MCP servers via integrations UI in settings +* Access to tools, prompts, and resources from configured MCP servers +* Seamless integration with Claude's conversational interface +* Enterprise-grade security and compliance features + +### Claude Desktop App + +The Claude desktop application provides comprehensive support for MCP, enabling deep integration with local tools and data sources. + +**Key features:** + +* Full support for resources, allowing attachment of local files and data +* Support for prompt templates +* Tool integration for executing commands and scripts +* Local server connections for enhanced privacy and security + +### Chorus + +[Chorus](https://chorus.sh) is a native Mac app for chatting with AIs. Chat with multiple models at once, run tools and MCPs, create projects, quick chat, bring your own key, all in a blazing fast, keyboard shortcut friendly app. + +**Key features:** + +* MCP support with one-click install +* Built in tools, like web search, terminal, and image generation +* Chat with multiple models at once (cloud or local) +* Create projects with scoped memory +* Quick chat with an AI that can see your screen + +### Cline + +[Cline](https://github.com/cline/cline) is an autonomous coding agent in VS Code that edits files, runs commands, uses a browser, and more–with your permission at each step. + +**Key features:** + +* Create and add tools through natural language (e.g. "add a tool that searches the web") +* Share custom MCP servers Cline creates with others via the `~/Documents/Cline/MCP` directory +* Displays configured MCP servers along with their tools, resources, and any error logs + +### CodeGPT + +[CodeGPT](https://codegpt.co) is a popular VS Code and Jetbrains extension that brings AI-powered coding assistance to your editor. It supports integration with MCP servers for tools, allowing users to leverage external AI capabilities directly within their development workflow. + +**Key features:** + +* Use MCP tools from any configured MCP server +* Seamless integration with VS Code and Jetbrains UI +* Supports multiple LLM providers and custom endpoints + +**Learn more:** + +* [CodeGPT Documentation](https://docs.codegpt.co/) + +### Continue + +[Continue](https://github.com/continuedev/continue) is an open-source AI code assistant, with built-in support for all MCP features. + +**Key features:** + +* Type "@" to mention MCP resources +* Prompt templates surface as slash commands +* Use both built-in and MCP tools directly in chat +* Supports VS Code and JetBrains IDEs, with any LLM + +### Copilot-MCP + +[Copilot-MCP](https://github.com/VikashLoomba/copilot-mcp) enables AI coding assistance via MCP. + +**Key features:** + +* Support for MCP tools and resources +* Integration with development workflows +* Extensible AI capabilities + +### Cursor + +[Cursor](https://docs.cursor.com/advanced/model-context-protocol) is an AI code editor. + +**Key features:** + +* Support for MCP tools in Cursor Composer +* Support for both STDIO and SSE + +### Daydreams + +[Daydreams](https://github.com/daydreamsai/daydreams) is a generative agent framework for executing anything onchain + +**Key features:** + +* Supports MCP Servers in config +* Exposes MCP Client + +### Emacs Mcp + +[Emacs Mcp](https://github.com/lizqwerscott/mcp.el) is an Emacs client designed to interface with MCP servers, enabling seamless connections and interactions. It provides MCP tool invocation support for AI plugins like [gptel](https://github.com/karthink/gptel) and [llm](https://github.com/ahyatt/llm), adhering to Emacs' standard tool invocation format. This integration enhances the functionality of AI tools within the Emacs ecosystem. + +**Key features:** + +* Provides MCP tool support for Emacs. + +### fast-agent + +[fast-agent](https://github.com/evalstate/fast-agent) is a Python Agent framework, with simple declarative support for creating Agents and Workflows, with full multi-modal support for Anthropic and OpenAI models. + +**Key features:** + +* PDF and Image support, based on MCP Native types +* Interactive front-end to develop and diagnose Agent applications, including passthrough and playback simulators +* Built in support for "Building Effective Agents" workflows. +* Deploy Agents as MCP Servers + +### FlowDown + +[FlowDown](https://github.com/Lakr233/FlowDown) is a blazing fast and smooth client app for using AI/LLM, with a strong emphasis on privacy and user experience. It supports MCP servers to extend its capabilities with external tools, allowing users to build powerful, customized workflows. + +**Key features:** + +* **Seamless MCP Integration**: Easily connect to MCP servers to utilize a wide range of external tools. +* **Privacy-First Design**: Your data stays on your device. We don't collect any user data, ensuring complete privacy. +* **Lightweight & Efficient**: A compact and optimized design ensures a smooth and responsive experience with any AI model. +* **Broad Compatibility**: Works with all OpenAI-compatible service providers and supports local offline models through MLX. +* **Rich User Experience**: Features beautifully formatted Markdown, blazing-fast text rendering, and intelligent, automated chat titling. + +**Learn more:** + +* [FlowDown website](https://flowdown.ai/) +* [FlowDown documentation](https://apps.qaq.wiki/docs/flowdown/) + +### FLUJO + +Think n8n + ChatGPT. FLUJO is an desktop application that integrates with MCP to provide a workflow-builder interface for AI interactions. Built with Next.js and React, it supports both online and offline (ollama) models, it manages API Keys and environment variables centrally and can install MCP Servers from GitHub. FLUJO has an ChatCompletions endpoint and flows can be executed from other AI applications like Cline, Roo or Claude. + +**Key features:** + +* Environment & API Key Management +* Model Management +* MCP Server Integration +* Workflow Orchestration +* Chat Interface + +### Genkit + +[Genkit](https://github.com/firebase/genkit) is a cross-language SDK for building and integrating GenAI features into applications. The [genkitx-mcp](https://github.com/firebase/genkit/tree/main/js/plugins/mcp) plugin enables consuming MCP servers as a client or creating MCP servers from Genkit tools and prompts. + +**Key features:** + +* Client support for tools and prompts (resources partially supported) +* Rich discovery with support in Genkit's Dev UI playground +* Seamless interoperability with Genkit's existing tools and prompts +* Works across a wide variety of GenAI models from top providers + +### Glama + +[Glama](https://glama.ai/chat) is a comprehensive AI workspace and integration platform that offers a unified interface to leading LLM providers, including OpenAI, Anthropic, and others. It supports the Model Context Protocol (MCP) ecosystem, enabling developers and enterprises to easily discover, build, and manage MCP servers. + +**Key features:** + +* Integrated [MCP Server Directory](https://glama.ai/mcp/servers) +* Integrated [MCP Tool Directory](https://glama.ai/mcp/tools) +* Host MCP servers and access them via the Chat or SSE endpoints + – Ability to chat with multiple LLMs and MCP servers at once +* Upload and analyze local files and data +* Full-text search across all your chats and data + +### GenAIScript + +Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft.github.io/genaiscript/) (in JavaScript). Orchestrate LLMs, tools, and data in JavaScript. + +**Key features:** + +* JavaScript toolbox to work with prompts +* Abstraction to make it easy and productive +* Seamless Visual Studio Code integration + +### Goose + +[Goose](https://github.com/block/goose) is an open source AI agent that supercharges your software development by automating coding tasks. + +**Key features:** + +* Expose MCP functionality to Goose through tools. +* MCPs can be installed directly via the [extensions directory](https://block.github.io/goose/v1/extensions/), CLI, or UI. +* Goose allows you to extend its functionality by [building your own MCP servers](https://block.github.io/goose/docs/tutorials/custom-extensions). +* Includes built-in tools for development, web scraping, automation, memory, and integrations with JetBrains and Google Drive. + +### GitHub Copilot coding agent + +Delegate tasks to [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/about-copilot-coding-agent) and let it work in the background while you stay focused on the highest-impact and most interesting work + +**Key features:** + +* Delegate tasks to Copilot from GitHub Issues, Visual Studio Code, GitHub Copilot Chat or from your favorite MCP host using the GitHub MCP Server +* Tailor Copilot to your project by [customizing the agent's development environment](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/customizing-the-development-environment-for-copilot-coding-agent#preinstalling-tools-or-dependencies-in-copilots-environment) or [writing custom instructions](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository) +* [Augment Copilot's context and capabilities with MCP tools](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp), with support for both local and remote MCP servers + +### gptme + +[gptme](https://github.com/gptme/gptme) is a open-source terminal-based personal AI assistant/agent, designed to assist with programming tasks and general knowledge work. + +**Key features:** + +* CLI-first design with a focus on simplicity and ease of use +* Rich set of built-in tools for shell commands, Python execution, file operations, and web browsing +* Local-first approach with support for multiple LLM providers +* Open-source, built to be extensible and easy to modify + +### HyperAgent + +[HyperAgent](https://github.com/hyperbrowserai/HyperAgent) is Playwright supercharged with AI. With HyperAgent, you no longer need brittle scripts, just powerful natural language commands. Using MCP servers, you can extend the capability of HyperAgent, without having to write any code. + +**Key features:** + +* AI Commands: Simple APIs like page.ai(), page.extract() and executeTask() for any AI automation +* Fallback to Regular Playwright: Use regular Playwright when AI isn't needed +* Stealth Mode – Avoid detection with built-in anti-bot patches +* Cloud Ready – Instantly scale to hundreds of sessions via [Hyperbrowser](https://www.hyperbrowser.ai/) +* MCP Client – Connect to tools like Composio for full workflows (e.g. writing web data to Google Sheets) + +### JetBrains AI Assistant + +[JetBrains AI Assistant](https://plugins.jetbrains.com/plugin/22282-jetbrains-ai-assistant) plugin provides AI-powered features for software development available in all JetBrains IDEs. + +**Key features:** + +* Unlimited code completion powered by Mellum, JetBrains’ proprietary AI model. +* Context-aware AI chat that understands your code and helps you in real time. +* Access to top-tier models from OpenAI, Anthropic, and Google. +* Offline mode with connected local LLMs via Ollama or LM Studio. +* Deep integration into IDE workflows, including code suggestions in the editor, VCS assistance, runtime error explanation, and more. + +### Kilo Code + +[Kilo Code](https://github.com/Kilo-Org/kilocode) is an autonomous coding AI dev team in VS Code that edits files, runs commands, uses a browser, and more. + +**Key features:** + +* Create and add tools through natural language (e.g. "add a tool that searches the web") +* Discover MCP servers via the MCP Marketplace +* One click MCP server installs via MCP Marketplace +* Displays configured MCP servers along with their tools, resources, and any error logs + +### Klavis AI Slack/Discord/Web + +[Klavis AI](https://www.klavis.ai/) is an Open-Source Infra to Use, Build & Scale MCPs with ease. + +**Key features:** + +* Slack/Discord/Web MCP clients for using MCPs directly +* Simple web UI dashboard for easy MCP configuration +* Direct OAuth integration with Slack & Discord Clients and MCP Servers for secure user authentication +* SSE transport support +* Open-source infrastructure ([GitHub repository](https://github.com/Klavis-AI/klavis)) + +**Learn more:** + +* [Demo video showing MCP usage in Slack/Discord](https://youtu.be/9-QQAhrQWw8) + +### LibreChat + +[LibreChat](https://github.com/danny-avila/LibreChat) is an open-source, customizable AI chat UI that supports multiple AI providers, now including MCP integration. + +**Key features:** + +* Extend current tool ecosystem, including [Code Interpreter](https://www.librechat.ai/docs/features/code_interpreter) and Image generation tools, through MCP servers +* Add tools to customizable [Agents](https://www.librechat.ai/docs/features/agents), using a variety of LLMs from top providers +* Open-source and self-hostable, with secure multi-user support +* Future roadmap includes expanded MCP feature support + +### LM Studio + +[LM Studio](https://lmstudio.ai) is a cross-platform desktop app for discovering, downloading, and running open-source LLMs locally. You can now connect local models to tools via Model Context Protocol (MCP). + +**Key features:** + +* Use MCP servers with local models on your computer. Add entries to `mcp.json` and save to get started. +* Tool confirmation UI: when a model calls a tool, you can confirm the call in the LM Studio app. +* Cross-platform: runs on macOS, Windows, and Linux, one-click installer with no need to fiddle in the command line +* Supports GGUF (llama.cpp) or MLX models with GPU acceleration +* GUI & terminal mode: use the LM Studio app or CLI (lms) for scripting and automation + +**Learn more:** + +* [Docs: Using MCP in LM Studio](https://lmstudio.ai/docs/app/plugins/mcp) +* [Create a 'Add to LM Studio' button for your server](https://lmstudio.ai/docs/app/plugins/mcp/deeplink) +* [Announcement blog: LM Studio + MCP](https://lmstudio.ai/blog/mcp) + +### Lutra + +[Lutra](https://lutra.ai) is an AI agent that transforms conversations into actionable, automated workflows. + +**Key features:** + +* Easy MCP Integration: Connecting Lutra to MCP servers is as simple as providing the server URL; Lutra handles the rest behind the scenes. +* Chat to Take Action: Lutra understands your conversational context and goals, automatically integrating with your existing apps to perform tasks. +* Reusable Playbooks: After completing a task, save the steps as reusable, automated workflows—simplifying repeatable processes and reducing manual effort. +* Shareable Automations: Easily share your saved playbooks with teammates to standardize best practices and accelerate collaborative workflows. + +**Learn more:** + +* [Lutra AI agent explained](https://www.youtube.com/watch?v=W5ZpN0cMY70) + +### mcp-agent + +[mcp-agent] is a simple, composable framework to build agents using Model Context Protocol. + +**Key features:** + +* Automatic connection management of MCP servers. +* Expose tools from multiple servers to an LLM. +* Implements every pattern defined in [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents). +* Supports workflow pause/resume signals, such as waiting for human feedback. + +### mcp-client-chatbot + +[mcp-client-chatbot](https://github.com/cgoinglove/mcp-client-chatbot) is a local-first chatbot built with Vercel's Next.js, AI SDK, and Shadcn UI. + +**Key features:** + +* It supports standard MCP tool calling and includes both a custom MCP server and a standalone UI for testing MCP tools outside the chat flow. +* All MCP tools are provided to the LLM by default, but the project also includes an optional `@toolname` mention feature to make tool invocation more explicit—particularly useful when connecting to multiple MCP servers with many tools. +* Visual workflow builder that lets you create custom tools by chaining LLM nodes and MCP tools together. Published workflows become callable as `@workflow_name` tools in chat, enabling complex multi-step automation sequences. + +### mcp-use + +[mcp-use] is an open source python library to very easily connect any LLM to any MCP server both locally and remotely. + +**Key features:** + +* Very simple interface to connect any LLM to any MCP. +* Support the creation of custom agents, workflows. +* Supports connection to multiple MCP servers simultaneously. +* Supports all langchain supported models, also locally. +* Offers efficient tool orchestration and search functionalities. + +### modelcontextchat.com + +[modelcontextchat.com](https://modelcontextchat.com) is a web-based MCP client designed for working with remote MCP servers, featuring comprehensive authentication support and integration with OpenRouter. + +**Key features:** + +* Web-based interface for remote MCP server connections +* Header-based Authorization support for secure server access +* OAuth authentication integration +* OpenRouter API Key support for accessing various LLM providers +* No installation required - accessible from any web browser + +### MCPHub + +[MCPHub] is a powerful Neovim plugin that integrates MCP (Model Context Protocol) servers into your workflow. + +**Key features:** + +* Install, configure and manage MCP servers with an intuitive UI. +* Built-in Neovim MCP server with support for file operations (read, write, search, replace), command execution, terminal integration, LSP integration, buffers, and diagnostics. +* Create Lua-based MCP servers directly in Neovim. +* Inegrates with popular Neovim chat plugins Avante.nvim and CodeCompanion.nvim + +### MCPOmni-Connect + +[MCPOmni-Connect](https://github.com/Abiorh001/mcp_omni_connect) is a versatile command-line interface (CLI) client designed to connect to various Model Context Protocol (MCP) servers using both stdio and SSE transport. + +**Key features:** + +* Support for resources, prompts, tools, and sampling +* Agentic mode with ReAct and orchestrator capabilities +* Seamless integration with OpenAI models and other LLMs +* Dynamic tool and resource management across multiple servers +* Support for both stdio and SSE transport protocols +* Comprehensive tool orchestration and resource analysis capabilities + +### Memex + +[Memex](https://memex.tech/) is the first MCP client and MCP server builder - all-in-one desktop app. Unlike traditional MCP clients that only consume existing servers, Memex can create custom MCP servers from natural language prompts, immediately integrate them into its toolkit, and use them to solve problems—all within a single conversation. + +**Key features:** + +* **Prompt-to-MCP Server**: Generate fully functional MCP servers from natural language descriptions +* **Self-Testing & Debugging**: Autonomously test, debug, and improve created MCP servers +* **Universal MCP Client**: Works with any MCP server through intuitive, natural language integration +* **Curated MCP Directory**: Access to tested, one-click installable MCP servers (Neon, Netlify, GitHub, Context7, and more) +* **Multi-Server Orchestration**: Leverage multiple MCP servers simultaneously for complex workflows + +**Learn more:** + +* [Memex Launch 2: MCP Teams and Agent API](https://memex.tech/blog/memex-launch-2-mcp-teams-and-agent-api-private-preview-125f) + +### Microsoft Copilot Studio + +[Microsoft Copilot Studio] is a robust SaaS platform designed for building custom AI-driven applications and intelligent agents, empowering developers to create, deploy, and manage sophisticated AI solutions. + +**Key features:** + +* Support for MCP tools +* Extend Copilot Studio agents with MCP servers +* Leveraging Microsoft unified, governed, and secure API management solutions + +### MindPal + +[MindPal](https://mindpal.io) is a no-code platform for building and running AI agents and multi-agent workflows for business processes. + +**Key features:** + +* Build custom AI agents with no-code +* Connect any SSE MCP server to extend agent tools +* Create multi-agent workflows for complex business processes +* User-friendly for both technical and non-technical professionals +* Ongoing development with continuous improvement of MCP support + +**Learn more:** + +* [MindPal MCP Documentation](https://docs.mindpal.io/agent/mcp) + +### MooPoint + +[MooPoint](https://moopoint.io) + +MooPoint is a web-based AI chat platform built for developers and advanced users, letting you interact with multiple large language models (LLMs) through a single, unified interface. Connect your own API keys (OpenAI, Anthropic, and more) and securely manage custom MCP server integrations. + +**Key features:** + +* Accessible from any PC or smartphone—no installation required +* Choose your preferred LLM provider +* Supports `SSE`, `Streamable HTTP`, `npx`, and `uvx` MCP servers +* OAuth and sampling support +* New features added daily + +### Msty Studio + +[Msty Studio](https://msty.ai) is a privacy-first AI productivity platform that seamlessly integrates local and online language models (LLMs) into customizable workflows. Designed for both technical and non-technical users, Msty Studio offers a suite of tools to enhance AI interactions, automate tasks, and maintain full control over data and model behavior. + +**Key features:** + +* **Toolbox & Toolsets**: Connect AI models to local tools and scripts using MCP-compliant configurations. Group tools into Toolsets to enable dynamic, multi-step workflows within conversations. +* **Turnstiles**: Create automated, multi-step AI interactions, allowing for complex data processing and decision-making flows. +* **Real-Time Data Integration**: Enhance AI responses with up-to-date information by integrating real-time web search capabilities. +* **Split Chats & Branching**: Engage in parallel conversations with multiple models simultaneously, enabling comparative analysis and diverse perspectives. + +**Learn more:** + +* [Msty Studio Documentation](https://docs.msty.studio/features/toolbox/tools) + +### NVIDIA Agent Intelligence (AIQ) toolkit + +[NVIDIA Agent Intelligence (AIQ) toolkit](https://github.com/NVIDIA/AIQToolkit) is a flexible, lightweight, and unifying library that allows you to easily connect existing enterprise agents to data sources and tools across any framework. + +**Key features:** + +* Acts as an MCP **client** to consume remote tools +* Acts as an MCP **server** to expose tools +* Framework agnostic and compatible with LangChain, CrewAI, Semantic Kernel, and custom agents +* Includes built-in observability and evaluation tools + +**Learn more:** + +* [AIQ toolkit GitHub repository](https://github.com/NVIDIA/AIQToolkit) +* [AIQ toolkit MCP documentation](https://docs.nvidia.com/aiqtoolkit/latest/workflows/mcp/index.html) + +### OpenSumi + +[OpenSumi](https://github.com/opensumi/core) is a framework helps you quickly build AI Native IDE products. + +**Key features:** + +* Supports MCP tools in OpenSumi +* Supports built-in IDE MCP servers and custom MCP servers + +### oterm + +[oterm] is a terminal client for Ollama allowing users to create chats/agents. + +**Key features:** + +* Support for multiple fully customizable chat sessions with Ollama connected with tools. +* Support for MCP tools. + +### Roo Code + +[Roo Code](https://roocode.com) enables AI coding assistance via MCP. + +**Key features:** + +* Support for MCP tools and resources +* Integration with development workflows +* Extensible AI capabilities + +### Postman + +[Postman](https://postman.com/downloads) is the most popular API client and now supports MCP server testing and debugging. + +**Key features:** + +* Full support of all major MCP features (tools, prompts, resources, and subscriptions) +* Fast, seamless UI for debugging MCP capabilities +* MCP config integration (Claude, VSCode, etc.) for fast first-time experience in testing MCPs +* Integration with history, variables, and collections for reuse and collaboration + +### RecurseChat + +[RecurseChat](https://recurse.chat) is a powerful, fast, local-first chat client with MCP support. RecurseChat supports multiple AI providers including LLaMA.cpp, Ollama, and OpenAI, Anthropic. + +**Key features:** + +* Local AI: Support MCP with Ollama models. +* MCP Tools: Individual MCP server management. Easily visualize the connection states of MCP servers. +* MCP Import: Import configuration from Claude Desktop app or JSON + +**Learn more:** + +* [RecurseChat docs](https://recurse.chat/docs/features/mcp/) + +### Shortwave + +[Shortwave](https://www.shortwave.com) is an AI-powered email client that supports MCP tools to enhance email productivity and workflow automation. + +**Key features:** + +* MCP tool integration for enhanced email workflows +* Rich UI for adding, managing and interacting with a wide range of MCP servers +* Support for both remote (Streamable HTTP and SSE) and local (Stdio) MCP servers +* AI assistance for managing your emails, calendar, tasks and other third-party services + +### Slack MCP Client + +[Slack MCP Client](https://github.com/tuannvm/slack-mcp-client) acts as a bridge between Slack and Model Context Protocol (MCP) servers. Using Slack as the interface, it enables large language models (LLMs) to connect and interact with various MCP servers through standardized MCP tools. + +**Key features:** + +* **Supports Popular LLM Providers:** Integrates seamlessly with leading large language model providers such as OpenAI, Anthropic, and Ollama, allowing users to leverage advanced conversational AI and orchestration capabilities within Slack. +* **Dynamic and Secure Integration:** Supports dynamic registration of MCP tools, works in both channels and direct messages and manages credentials securely via environment variables or Kubernetes secrets. +* **Easy Deployment and Extensibility:** Offers official Docker images, a Helm chart for Kubernetes, and Docker Compose for local development, making it simple to deploy, configure, and extend with additional MCP servers or tools. + +### Sourcegraph Cody + +[Cody](https://openctx.org/docs/providers/modelcontextprotocol) is Sourcegraph's AI coding assistant, which implements MCP through OpenCTX. + +**Key features:** + +* Support for MCP resources +* Integration with Sourcegraph's code intelligence +* Uses OpenCTX as an abstraction layer +* Future support planned for additional MCP features + +### SpinAI + +[SpinAI](https://spinai.dev) is an open-source TypeScript framework for building observable AI agents. The framework provides native MCP compatibility, allowing agents to seamlessly integrate with MCP servers and tools. + +**Key features:** + +* Built-in MCP compatibility for AI agents +* Open-source TypeScript framework +* Observable agent architecture +* Native support for MCP tools integration + +### Superinterface + +[Superinterface](https://superinterface.ai) is AI infrastructure and a developer platform to build in-app AI assistants with support for MCP, interactive components, client-side function calling and more. + +**Key features:** + +* Use tools from MCP servers in assistants embedded via React components or script tags +* SSE transport support +* Use any AI model from any AI provider (OpenAI, Anthropic, Ollama, others) + +### Superjoin + +[Superjoin](https://superjoin.ai) brings the power of MCP directly into Google Sheets extension. With Superjoin, users can access and invoke MCP tools and agents without leaving their spreadsheets, enabling powerful AI workflows and automation right where their data lives. + +**Key features:** + +* Native Google Sheets add-on providing effortless access to MCP capabilities +* Supports OAuth 2.1 and header-based authentication for secure and flexible connections +* Compatible with both SSE and Streamable HTTP transport for efficient, real-time streaming communication +* Fully web-based, cross-platform client requiring no additional software installation + +### systemprompt + +[systemprompt](https://systemprompt.io) is a voice-controlled mobile app that manages your MCP servers. Securely leverage MCP agents from your pocket. Available on iOS and Android. + +**Key features:** + +* **Native Mobile Experience**: Access and manage your MCP servers anytime, anywhere on both Android and iOS devices +* **Advanced AI-Powered Voice Recognition**: Sophisticated voice recognition engine enhanced with cutting-edge AI and Natural Language Processing (NLP), specifically tuned to understand complex developer terminology and command structures +* **Unified Multi-MCP Server Management**: Effortlessly manage and interact with multiple Model Context Protocol (MCP) servers from a single, centralized mobile application + +### Tambo + +[Tambo](https://tambo.co) is a platform for building custom chat experiences in React, with integrated custom user interface components. + +**Key features:** + +* Hosted platform with React SDK for integrating chat or other LLM-based experiences into your own app. +* Support for selection of arbitrary React components in the chat experience, with state management and tool calling. +* Support for MCP servers, from Tambo's servers or directly from the browser. +* Supports OAuth 2.1 and custom header-based authentication. +* Support for MCP tools, with additional MCP features coming soon. + +### Tencent CloudBase AI DevKit + +[Tencent CloudBase AI DevKit](https://docs.cloudbase.net/ai/agent/mcp) is a tool for building AI agents in minutes, featuring zero-code tools, secure data integration, and extensible plugins via MCP. + +**Key features:** + +* Support for MCP tools +* Extend agents with MCP servers +* MCP servers hosting: serverless hosting and authentication support + +### TheiaAI/TheiaIDE + +[Theia AI](https://eclipsesource.com/blogs/2024/10/07/introducing-theia-ai/) is a framework for building AI-enhanced tools and IDEs. The [AI-powered Theia IDE](https://eclipsesource.com/blogs/2024/10/08/introducting-ai-theia-ide/) is an open and flexible development environment built on Theia AI. + +**Key features:** + +* **Tool Integration**: Theia AI enables AI agents, including those in the Theia IDE, to utilize MCP servers for seamless tool interaction. +* **Customizable Prompts**: The Theia IDE allows users to define and adapt prompts, dynamically integrating MCP servers for tailored workflows. +* **Custom agents**: The Theia IDE supports creating custom agents that leverage MCP capabilities, enabling users to design dedicated workflows on the fly. + +Theia AI and Theia IDE's MCP integration provide users with flexibility, making them powerful platforms for exploring and adapting MCP. + +**Learn more:** + +* [Theia IDE and Theia AI MCP Announcement](https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/) +* [Download the AI-powered Theia IDE](https://theia-ide.org/) + +### Tome + +[Tome](https://github.com/runebookai/tome) is an open source cross-platform desktop app designed for working with local LLMs and MCP servers. It is designed to be beginner friendly and abstract away the nitty gritty of configuration for people getting started with MCP. + +**Key features:** + +* MCP servers are managed by Tome so there is no need to install uv or npm or configure JSON +* Users can quickly add or remove MCP servers via UI +* Any tool-supported local model on Ollama is compatible + +### TypingMind App + +[TypingMind](https://www.typingmind.com) is an advanced frontend for LLMs with MCP support. TypingMind supports all popular LLM providers like OpenAI, Gemini, Claude, and users can use with their own API keys. + +**Key features:** + +* **MCP Tool Integration**: Once MCP is configured, MCP tools will show up as plugins that can be enabled/disabled easily via the main app interface. +* **Assign MCP Tools to Agents**: TypingMind allows users to create AI agents that have a set of MCP servers assigned. +* **Remote MCP servers**: Allows users to customize where to run the MCP servers via its MCP Connector configuration, allowing the use of MCP tools across multiple devices (laptop, mobile devices, etc.) or control MCP servers from a remote private server. + +**Learn more:** + +* [TypingMind MCP Document](https://www.typingmind.com/mcp) +* [Download TypingMind (PWA)](https://www.typingmind.com/) + +### VS Code GitHub Copilot + +[VS Code](https://code.visualstudio.com/) integrates MCP with GitHub Copilot through [agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode), allowing direct interaction with MCP-provided tools within your agentic coding workflow. Configure servers in Claude Desktop, workspace or user settings, with guided MCP installation and secure handling of keys in input variables to avoid leaking hard-coded keys. + +**Key features:** + +* Support for stdio and server-sent events (SSE) transport +* Per-session selection of tools per agent session for optimal performance +* Easy server debugging with restart commands and output logging +* Tool calls with editable inputs and always-allow toggle +* Integration with existing VS Code extension system to register MCP servers from extensions + +### Warp + +[Warp](https://www.warp.dev/) is the intelligent terminal with AI and your dev team's knowledge built-in. With natural language capabilities integrated directly into an agentic command line, Warp enables developers to code, automate, and collaborate more efficiently -- all within a terminal that features a modern UX. + +**Key features:** + +* **Agent Mode with MCP support**: invoke tools and access data from MCP servers using natural language prompts +* **Flexible server management**: add and manage CLI or SSE-based MCP servers via Warp's built-in UI +* **Live tool/resource discovery**: view tools and resources from each running MCP server +* **Configurable startup**: set MCP servers to start automatically with Warp or launch them manually as needed + +### WhatsMCP + +[WhatsMCP](https://wassist.app/mcp/) is an MCP client for WhatsApp. WhatsMCP lets you interact with your AI stack from the comfort of a WhatsApp chat. + +**Key features:** + +* Supports MCP tools +* SSE transport, full OAuth2 support +* Chat flow management for WhatsApp messages +* One click setup for connecting to your MCP servers +* In chat management of MCP servers +* Oauth flow natively supported in WhatsApp + +### Windsurf Editor + +[Windsurf Editor](https://codeium.com/windsurf) is an agentic IDE that combines AI assistance with developer workflows. It features an innovative AI Flow system that enables both collaborative and independent AI interactions while maintaining developer control. + +**Key features:** + +* Revolutionary AI Flow paradigm for human-AI collaboration +* Intelligent code generation and understanding +* Rich development tools with multi-model support + +### Witsy + +[Witsy](https://github.com/nbonamy/witsy) is an AI desktop assistant, supporting Anthropic models and MCP servers as LLM tools. + +**Key features:** + +* Multiple MCP servers support +* Tool integration for executing commands and scripts +* Local server connections for enhanced privacy and security +* Easy-install from Smithery.ai +* Open-source, available for macOS, Windows and Linux + +### Zed + +[Zed](https://zed.dev/docs/assistant/model-context-protocol) is a high-performance code editor with built-in MCP support, focusing on prompt templates and tool integration. + +**Key features:** + +* Prompt templates surface as slash commands in the editor +* Tool integration for enhanced coding workflows +* Tight integration with editor features and workspace context +* Does not support MCP resources + +### Zencoder + +[Zencoder](https://zecoder.ai) is a coding agent that's available as an extension for VS Code and JetBrains family of IDEs, meeting developers where they already work. It comes with RepoGrokking (deep contextual codebase understanding), agentic pipeline, and the ability to create and share custom agents. + +**Key features:** + +* RepoGrokking - deep contextual understanding of codebases +* Agentic pipeline - runs, tests, and executes code before outputting it +* Zen Agents platform - ability to build and create custom agents and share with the team +* Integrated MCP tool library with one-click installations +* Specialized agents for Unit and E2E Testing + +**Learn more:** + +* [Zencoder Documentation](https://docs.zencoder.ai) + +## Adding MCP support to your application + +If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem. + +Benefits of adding MCP support: + +* Enable users to bring their own context and tools +* Join a growing ecosystem of interoperable AI applications +* Provide users with flexible integration options +* Support local-first AI workflows + +To get started with implementing MCP in your application, check out our [Python](https://github.com/modelcontextprotocol/python-sdk) or [TypeScript SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) + +## Updates and corrections + +This list is maintained by the community. If you notice any inaccuracies or would like to update information about MCP support in your application, please submit a pull request or [open an issue in our documentation repository](https://github.com/modelcontextprotocol/modelcontextprotocol/issues). + + +# Contributor Communication +Source: https://modelcontextprotocol.io/community/communication + +Communication strategy and framework for the Model Context Protocol community + +This document explains how to communicate and collaborate within the Model Context Protocol (MCP) project. + +## Communication Channels + +In short: + +* **[Discord][discord-join]**: For real-time or ad-hoc discussions. +* **[GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions)**: For structured, longer-form discussions. +* **[GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues)**: For actionable tasks, bug reports, and feature requests. +* **For security-sensitive issues**: Follow the process in [SECURITY.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/SECURITY.md). + +All communication is governed by our [Code of Conduct](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CODE_OF_CONDUCT.md). We expect all participants to maintain respectful, professional, and inclusive interactions across all channels. + +### Discord + +For real-time contributor discussion and collaboration. The server is designed around **MCP contributors** and is not intended +to be a place for general MCP support. + +The Discord server will have both public and private channels. + +[Join the Discord server here][discord-join]. + +#### Public Channels (Default) + +* **Purpose**: Open community engagement, collaborative development, and transparent project coordination. +* Primary use cases: + * **Public SDK and tooling development**: All development, from ideation to release planning, happens in public channels (e.g., `#typescript-sdk-dev`, `#inspector-dev`). + * **Working and interest group discussions** (`#client-implementors`, `#agents-wg`, etc.) + * **Working Group**: Some specific goal or project in mind (such as an SDK, inspector, registry, server-identity, load-balancing, etc). + * **Interest Group**: An abstract gathering of folks that might raise a range of various topics. Some might get actioned on as one-offs, others might spin into Working Groups. + * **Community onboarding** and contribution guidance. + * **Community feedback** and collaborative brainstorming. + * Public **office hours** and **maintainer availability**. +* Avoid: + * MCP user support: participants are expected to read official documentation and start new GitHub Discussions for questions or support. + * Service or product marketing: interactions on this Discord are expected to be vendor-neutral and not used for brand-building or sales. Mentions of brands or products are discouraged outside of being used as examples or responses to conversations that start off focused on the specification. + +#### Private channels (Exceptions) + +* **Purpose**: Confidential coordination and sensitive matters that cannot be discussed publicly. Access will be restricted to designated maintainers. +* **Strict criteria for private use**: + * **Security incidents** (CVEs, protocol vulnerabilities). + * **People matters** (maintainer-related discussions, code of conduct policies). + * Select channels will be configured to be **read-only**. This can be good for example for maintainer decision making. + * Coordination requiring **immediate** or otherwise **focused response** with a limited audience. +* **Transparency**: + * **All technical and governance decisions** affecting the community **must be documented** in GitHub Discussions and/or Issues, and will be labeled with `notes`. + * **Some matters related to individual contributors** may remain private when appropriate (e.g., personal circumstances, disciplinary actions, or other sensitive individual matters). + * Private channels are to be used as **temporary "incident rooms,"** not for routine development. + +Any significant discussion on Discord that leads to a potential decision or proposal must be moved to a GitHub Discussion or GitHub Issue to create a persistent, searchable record. Proposals will then be promoted to full-fledged PRs with associated work items (GitHub Issues) as needed. + +### GitHub Discussions + +For structured, long-form discussion and debate on project direction, features, improvements, and community topics. + +When to use: + +* Project roadmap planning and milestone discussions +* Announcements and release communications +* Community polls and consensus-building processes +* Feature requests with context and rationale + * If a particular repository does not have GitHub Discussions enabled, feel free to open a GitHub Issue instead. + +### GitHub Issues + +For bug reports, feature tracking, and actionable development tasks. + +When to use: + +* Submit SEP proposals (following the [SEP guidelines](./sep-guidelines)) +* Bug reports with reproducible steps +* Documentation improvements with specific scope +* CI/CD problems and infrastructure issues +* Release tasks and milestone tracking + +### Security Issues + +**Do not post security issues publicly.** Instead: + +1. Use the private security reporting process. For protocol-level security issues, follow the process in [SECURITY.md in the modelcontextprotocol GitHub repository](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/SECURITY.md). +2. Contact lead and/or [core maintainers](./governance#current-core-maintainers) directly. +3. Follow responsible disclosure guidelines. + +## Decision Records + +All MCP decisions are documented and captured in public channels. + +* **Technical decisions**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and SEPs. +* **Specification changes**: [On the Model Context Protocol website](https://modelcontextprotocol.io/specification/draft/changelog). +* **Process changes**: [Community documentation](https://modelcontextprotocol.io/community/governance). +* **Governance decisions and updates**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and SEPs. + +When documenting decisions, we will retain as much context as possible: + +* Decision makers +* Background context and motivation +* Options that were considered +* Rationale for the chosen approach +* Implementation steps + +[discord-join]: https://discord.gg/6CSzBmMkjX + + +# Governance and Stewardship +Source: https://modelcontextprotocol.io/community/governance + +Learn about the Model Context Protocol's governance structure and how to participate in the community + +The Model Context Protocol (MCP) follows a formal governance model to ensure transparent decision-making and community participation. This document outlines how the project is organized and how decisions are made. + +## Technical Governance + +The MCP project adopts a hierarchical structure, similar to Python, PyTorch and other open source projects: + +* A community of **contributors** who file issues, make pull requests, and contribute to the project. +* A small set of **maintainers** drive components within the MCP project, such as SDKs, documentation, and others. +* Contributors and maintainers are overseen by **core maintainers**, who drive the overall project direction. +* The core maintainers have two **lead core maintainers** who are the catch-all decision makers. +* Maintainers, core maintainers, and lead core maintainers form the **MCP steering group**. + +All maintainers are expected to have a strong bias towards MCP's design philosophy. Membership in the technical governance process is for individuals, not companies. That is, there are no seats reserved for specific companies, and membership is associated with the person rather than the company employing that person. This ensures that maintainers act in the best interests of the protocol itself and the open source community. + +### Channels + +Technical Governance is facilitated through a shared [Discord server](/community/communication#discord) of all **maintainers, core maintainers** and **lead maintainers**. Each maintainer group can choose additional communication channels, but all decisions and their supporting discussions must be recorded and made transparently available on the Discord server. + +### Maintainers + +Maintainers are responsible for individual projects or technical working groups within the MCP project. These generally are independent repositories such as language-specific SDKs, but can also extend to subdirectories of a repository, such as the MCP documentation. Maintainers may adopt their own rules and procedures for making decisions. Maintainers are expected to make decisions for their respective projects independently, but can defer or escalate to the core maintainers when needed. + +Maintainers are responsible for the: + +* Thoughtful and productive engagement with community contributors, +* Maintaining and improving their respective area of the MCP project, +* Supporting documentation, roadmaps and other adjacent parts of the MCP project, +* Present ideas from community to core. + +Maintainers are encouraged to propose additional maintainers when needed. Maintainers can only be appointed and removed by core maintainers or lead core maintainers at any time and without reason. + +Maintainers have write and/or admin access to their respective repositories. + +### Core Maintainers + +The core maintainers are expected to have a deep understanding of the Model Context Protocol and its specification. Their responsibilities include: + +* Designing, reviewing and steering the evolution of the MCP specification, as well as all other parts of the MCP project, such as documentation, +* Articulating a cohesive long-term vision for the project, +* Mediating and resolving contentious issues with fairness and transparency, seeking consensus where possible while making decisive choices when necessary, +* Appoint or remove maintainers, +* Stewardship of the MCP project in the best interest of MCP. + +The core maintainers as a group have the power to veto any decisions made by maintainers by majority vote. The core maintainers have power to resolve disputes as they see fit. The core maintainers should publicly articulate their decision-making. The core group is responsible for adopting their own procedures for making decisions. + +Core maintainers generally have write and admin access to all MCP repositories, but should use the same contribution (usually pull-requests) mechanism as outside contributors. Exceptions can be made based on security considerations. + +### Lead Maintainers (BDFL) + +MCP has two lead maintainers: Justin Spahr-Summers and David Soria Parra. Lead Maintainers can veto any decision by core maintainers or maintainers. This model is also commonly known as Benevolent Dictator for Life (BDFL) in the open source community. The Lead Maintainers should publicly articulate their decision-making and give clear reasoning for their decisions. Lead maintainers are part of the core maintainer group. + +The Lead Maintainers are responsible for confirming or removing core maintainers. + +Lead Maintainers are administrators on all infrastructure for the MCP project where possible. This includes but is not restricted to all communication channels, GitHub organizations and repositories. + +### Decision Process + +The core maintainer group meets every two weeks to discuss and vote on proposals, as well as discuss any topics needed. The shared Discord server can be used to discuss and vote on smaller proposals if needed. + +The lead maintainer, core maintainer, and maintainer group should attempt to meet in person every three to six months. + +## Processes + +Core and lead maintainers are responsible for all aspects of Model Context Protocol, including documentation, issues, suggestions for content, and all other parts under the [MCP project](https://github.com/modelcontextprotocol). Maintainers are responsible for documentation, issues, and suggestions of content for their area of the MCP project, but are encouraged to partake in general maintenance of the MCP projects. Maintainers, core maintainers, and lead maintainers should use the same contribution process as external contributors, rather than making direct changes to repos. This provides insight into intent and opportunity for discussion. + +### Projects and Working Groups + +The MCP project is organized into two main structures: projects and working groups. + +Projects are concrete components maintained in dedicated repositories. These include the Specification, TypeScript SDK, Go SDK, Inspector, and other implementation artifacts. + +Working groups are forums for collaboration where interested parties discuss specific aspects of MCP without maintaining code repositories. These include groups focused on transport protocols, client implementation, and other cross-cutting concerns. + +#### Governance Principles + +All projects and working groups are self-governed while adhering to these core principles: + +1. Clear contribution and decision-making processes +2. Open communication and transparent decisions + +Both must: + +* Document their contribution process +* Maintain transparent communication +* Make decisions publicly (working groups must publish meeting notes and proposals) + +Projects and working groups without specified processes default to: + +* GitHub pull requests and issues for contributions +* A public channel in the official [MCP Contributor Discord](/community/communication#discord) + +#### Maintenance Responsibilities + +Components without dedicated maintainers (such as documentation) fall under core maintainer responsibility. These follow standard contribution guidelines through pull requests, with maintainers handling reviews and escalating to core maintainer review for any significant changes. + +Core maintainers and maintainers are encouraged to improve any part of the MCP project, regardless of formal maintenance assignments. + +### Specification Project + +#### Specification Enhancement Proposal (SEP) + +Proposed changes to the specification must come in the form of a written version, starting with a summary of the proposal, outlining the **problem** it tries to solve, propose **solution**, **alternatives**, **considerations, outcomes** and **risks**. The [SEP Guidelines](/community/sep-guidelines) outline information on the expected structure of SEPs. SEP's should be created as issues in the [specification repository](https://github.com/modelcontextprotocol/specification) and tagged with the labels `proposal, sep`. + +All proposals must have a **sponsor** from the MCP steering group (maintainer, core maintainer or lead core maintainer). The sponsor is responsible for ensuring that the proposal is actively developed, meets the quality standard for proposals and is responsible for presenting and discussing it in meetings of core maintainers. Maintainer and Core Maintainer groups should review open proposals without sponsors in regular intervals. Proposals that do not find a sponsor within six months are automatically rejected. + +Once proposals have a sponsor, they are assigned to the sponsor and are tagged `draft`. + +## Communication + +### Core Maintainer Meetings + +The core maintainer group meets on a bi-weekly basis to discuss proposals and the project. Notes on proposals should be made public. The core maintainer group will strive to meet in person every 3-6 months. + +### Public Chat + +The MCP project maintains a [public Discord server](/community/communication#discord) with open chats for interest groups. The MCP project may have private channels for certain communications. + +## Nominating, Confirming and Removing Maintainers + +### The Principles + +* Membership in module maintainer groups is given to **individuals** on merit basis after they demonstrated strong expertise of their area of work through contributions, reviews, and discussions and are aligned with the overall MCP direction. +* For membership in the **maintainer** group the individual has to demonstrate strong and continued alignment with the overall MCP principles. +* No term limits for module maintainers or core maintainers +* Light criteria of moving working-group or sub-project maintenance to 'emeritus' status if they don't actively participate over long periods of time. Each maintainer group may define the inactive period that's appropriate for their area. +* The membership is for an individual, not a company. + +### Nomination and Removal + +* Core Maintainers are responsible for adding and removing maintainers. They will take the consideration of existing maintainers into account. +* The lead maintainers are responsible for adding and removing core maintainers. + +#### Nomination Process + +If a Maintainer (or Core / Lead Maintainer) wishes to propose a nomination for the Core / Lead Maintainers’ consideration, they should follow the following process: + +1. Collect evidence for the nomination. This will generally come in the form of a history of merged PRs on the repositories for which maintainership is being considered. +2. Discuss among maintainers of the relevant group(s) as to whether they would be supportive of approving the nomination. +3. DM a Community Moderator or Core Maintainer to create a private channel in Discord, in the format `nomination-{name}-{group}`. Add all core maintainers, lead maintainers, and co-maintainers on the relevant group. +4. Provide context for the individual under nomination. See below for suggestions on what to include here. +5. Create a Discord Poll and ask Core / Lead Maintainers to vote Yes / No on the nomination. Reaching conesensus is encouraged though not required. +6. After Core / Lead Maintainers discuss and/or vote, if the nomination is favorable, relevant members with permissions to update GitHub an Discord roles will add the nominee to the appropriate groups. The nominator should announce the new maintainership in the relevant Discord channel. +7. The temporary Discord channel will be deleted a week later. + +Suggestions for the kind of information to share with core maintainers when nominating someone: + +* GitHub profile link, LinkedIn profile link, Discord username +* For what group(s) are you nominating the individual for maintainership +* Whether the group(s) agree that this person should be elevated to maintainership +* Description of their contributions to date (including links to most substantial contributions) +* Description of expected contributions moving forward (e.g. Are they eager to be a maintainer? Will they have capacity to do so?) +* Other context about the individual (e.g. current employer, motivations behind MCP involvement) +* Anything else you think may be relevant to consider for the nomination + +## Current Core Maintainers + +* Inna Harper +* Basil Hosmer +* Paul Carleton +* Nick Cooper +* Nick Aldridge +* Che Liu +* Den Delimarsky + +## Current Maintainers and Working Groups + +Refer to [the maintainer list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md). + + +# SEP Guidelines +Source: https://modelcontextprotocol.io/community/sep-guidelines + +Specification Enhancement Proposal (SEP) guidelines for proposing changes to the Model Context Protocol + +## What is a SEP? + +SEP stands for Specification Enhancement Proposal. A SEP is a design document providing information to the MCP community, or describing a new feature for the Model Context Protocol or its processes or environment. The SEP should provide a concise technical specification of the feature and a rationale for the feature. + +We intend SEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into MCP. The SEP author is responsible for building consensus within the community and documenting dissenting opinions. + +Because the SEPs are maintained as text files in a versioned repository (GitHub Issues), their revision history is the historical record of the feature proposal. + +## What qualifies a SEP? + +The goal is to reserve the SEP process for changes that are substantial enough to require broad community discussion, a formal design document, and a historical record of the decision-making process. A regular GitHub issue or pull request is often more appropriate for smaller, more direct changes. + +Consider proposing a SEP if your change involves any of the following: + +* **A New Feature or Protocol Change**: Any change that adds, modifies, or removes features in the Model Context Protocol. This includes: + * Adding new API endpoints or methods. + * Changing the syntax or semantics of existing data structures or messages. + * Introducing a new standard for interoperability between different MCP-compatible tools. + * Significant changes to how the specification itself is defined, presented, or validated. +* **A Breaking Change**: Any change that is not backwards-compatible. +* **A Change to Governance or Process**: Any proposal that alters the project's decision-making, contribution guidelines (like this document itself). +* **A Complex or Controversial Topic**: If a change is likely to have multiple valid solutions or generate significant debate, the SEP process provides the necessary framework to explore alternatives, document the rationale, and build community consensus before implementation begins. + +## SEP Types + +There are three kinds of SEP: + +1. **Standards Track** SEP describes a new feature or implementation for the Model Context Protocol. It may also describe an interoperability standard that will be supported outside the core protocol specification. +2. **Informational** SEP describes a Model Context Protocol design issue, or provides general guidelines or information to the MCP community, but does not propose a new feature. Informational SEPs do not necessarily represent an MCP community consensus or recommendation. +3. **Process** SEP describes a process surrounding MCP, or proposes a change to (or an event in) a process. Process SEPs are like Standards Track SEPs but apply to areas other than the MCP protocol itself. + +## Submitting a SEP + +The SEP process begins with a new idea for the Model Context Protocol. It is highly recommended that a single SEP contain a single key proposal or new idea. Small enhancements or patches often don't need a SEP and can be injected into the MCP development workflow with a pull request to the MCP repo. The more focused the SEP, the more successful it tends to be. + +Each SEP must have an **SEP author** -- someone who writes the SEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The SEP author should first attempt to ascertain whether the idea is SEP-able. Posting to the MCP community forums (Discord, GitHub Discussions) is the best way to go about this. + +### SEP Workflow + +SEPs should be submitted as a GitHub Issue in the [specification repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The standard SEP workflow is: + +1. You, the SEP author, create a [well-formatted](#sep-format) GitHub Issue with the `SEP` and `proposal` tags. The SEP number is the same as the GitHub Issue number, the two can be used interchangably. +2. Find a Core Maintainer or Maintainer to sponsor your proposal. Core Maintainers and Maintainers will regularly go over the list of open proposals to determine which proposals to sponsor. You can tag relevant maintainers from [the maintainer list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) in your proposal. +3. Once a sponsor is found, the GitHub Issue is assigned to the sponsor. The sponsor will add the `draft` tag, ensure the SEP number is in the title, and assign a milestone. +4. The sponsor will informally review the proposal and may request changes based on community feedback. When ready for formal review, the sponsor will add the `in-review` tag. +5. After the `in-review` tag is added, the SEP enters formal review by the Core Maintainers team. The SEP may be accepted, rejected, or returned for revision. +6. If the SEP has not found a sponsor within three months, Core Maintainers may close the SEP as `dormant`. + +### SEP Format + +Each SEP should have the following parts: + +1. **Preamble** -- A short descriptive title, the names and contact info for each author, the current status. +2. **Abstract** -- A short (\~200 word) description of the technical issue being addressed. +3. **Motivation** -- The motivation should clearly explain why the existing protocol specification is inadequate to address the problem that the SEP solves. The motivation is critical for SEPs that want to change the Model Context Protocol. SEP submissions without sufficient motivation may be rejected outright. +4. **Specification** -- The technical specification should describe the syntax and semantics of any new protocol feature. The specification should be detailed enough to allow competing, interoperable implementations. A PR with the changes to the specification should be provided. +5. **Rationale** -- The rationale explains why particular design decisions were made. It should describe alternate designs that were considered and related work. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion. +6. **Backward Compatibility** -- All SEPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The SEP must explain how the author proposes to deal with these incompatibilities. +7. **Reference Implementation** -- The reference implementation must be completed before any SEP is given status "Final", but it need not be completed before the SEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of protocol details. +8. **Security Implications** -- If there are security concerns in relation to the SEP, those concerns should be explicitly written out to make sure reviewers of the SEP are aware of them. + +### SEP States + +SEPs can be one one of the following states + +* `proposal`: SEP proposal without a sponsor. +* `draft`: SEP proposal with a sponsor. +* `in-review`: SEP proposal ready for review. +* `accepted`: SEP accepted by Core Maintainers, but still requires final wording and reference implementation. +* `rejected`: SEP rejected by Core Maintainers. +* `withdrawn`: SEP withdrawn. +* `final`: SEP finalized. +* `superseded`: SEP has been replaced by a newer SEP. +* `dormant`: SEP that has not found sponsors and was subsequently closed. + +### SEP Review & Resolution + +SEPs are reviewed by the MCP Core Maintainers team on a bi-weekly basis. + +For a SEP to be accepted it must meet certain minimum criteria: + +* A prototype implementation demonstrating the proposal +* Clear benefit to the MCP ecosystem +* Community support and consensus + +Once a SEP has been accepted, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to "Final". + +A SEP can also be "Rejected" or "Withdrawn". A SEP that is "Withdrawn" may be re-submitted at a later date. + +## Reporting SEP Bugs, or Submitting SEP Updates + +How you report a bug, or submit a SEP update depends on several factors, such as the maturity of the SEP, the preferences of the SEP author, and the nature of your comments. For SEPs not yet reaching `final` state, it's probably best to send your comments and changes directly to the SEP author. Once SEP is finalized, you may want to submit corrections as a GitHub comment on the issue or pull request to the reference implementation. + +## Transferring SEP Ownership + +It occasionally becomes necessary to transfer ownership of SEPs to a new SEP author. In general, we'd like to retain the original author as a co-author of the transferred SEP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the SEP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the SEP. We try to build consensus around a SEP, but if that's not possible, you can always submit a competing SEP. + +## Copyright + +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. + + +# Roadmap +Source: https://modelcontextprotocol.io/development/roadmap + +Our plans for evolving Model Context Protocol + +<Info>Last updated: **2025-07-22**</Info> + +The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and direction for approximately **the next six months**, though these may change significantly as the project develops. To see what's changed recently, check out the **[specification changelog](/specification/2025-06-18/changelog/)**. + +<Note> + The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an *exhaustive* list; we may incorporate work that isn't mentioned here. +</Note> + +We value community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts. + +For a technical view of our standardization process, visit the [Standards Track](https://github.com/orgs/modelcontextprotocol/projects/2/views/2) on GitHub, which tracks how proposals progress toward inclusion in the official [MCP specification](https://spec.modelcontextprotocol.io). + +## Agents + +As MCP increasingly becomes part of agentic workflows, we're focusing on key improvements: + +* **Asynchronous Operations**: supporting long-running operations that may take extended periods, with resilient handling of disconnections and reconnections + +## Authentication and Security + +We're evolving our authorization and security resources to improve user safety and provide a better developer experience: + +* **Guides and Best Practices**: documenting specifics about deploying MCP securely in the form of guides and best practices to help developers avoid common pitfalls. +* **Alternatives to Dynamic Client Registration (DCR)**: exploring alternatives to DCR, attempting to address operational challenges while preserving a smooth user experience. +* **Fine-grained Authorization**: developing mechanisms and guidelines for primitive authorization for sensitive actions +* **Enterprise Managed Authorization**: adding the capability for enterprises to simplify MCP server authorization with the help of Single Sign-On (SSO) +* **Secure Authorization Elicitation**: enable developers to integrate secure authorization flows for downstream APIs outside the main MCP server authorization + +## Validation + +To foster a robust developer ecosystem, we plan to invest in: + +* **Reference Client Implementations**: demonstrating protocol features with high-quality AI applications +* **Reference Server Implementation**: showcasing authentication patterns and remote deployment best practices +* **Compliance Test Suites**: automated verification that clients, servers, and SDKs properly implement the specification + +These tools will help developers confidently implement MCP while ensuring consistent behavior across the ecosystem. + +## Registry + +For MCP to reach its full potential, we need streamlined ways to distribute and discover MCP servers. + +We plan to develop an [**MCP Registry**](https://github.com/orgs/modelcontextprotocol/discussions/159) that will enable centralized server discovery and metadata. This registry will primarily function as an API layer that third-party marketplaces and discovery services can build upon. + +## Multimodality + +Supporting the full spectrum of AI capabilities in MCP, including: + +* **Additional Modalities**: video and other media types +* **[Streaming](https://github.com/modelcontextprotocol/specification/issues/117)**: multipart, chunked messages, and bidirectional communication for interactive experiences + +## Get Involved + +We welcome your contributions to MCP's future! Join our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to share ideas, provide feedback, or participate in the development process. + + +# Introduction +Source: https://modelcontextprotocol.io/docs/getting-started/intro + +Get started with the Model Context Protocol (MCP) + +MCP is an open protocol that standardizes how applications provide context to large language models (LLMs). Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. MCP enables you to build agents and complex workflows on top of LLMs and connects your models with the world. + +MCP provides: + +* **A growing list of pre-built integrations** that your LLM can directly plug into +* **A standardized way** to build custom integrations for AI applications +* **An open protocol** that everyone is free to implement and use +* **The flexibility to change** between different apps and take your context with you + +## Choose Your Path + +<CardGroup cols={2}> + <Card title="Understand Concepts" icon="book" href="/docs/learn/architecture"> + Learn the core concepts and architecture of MCP + </Card> + + {" "} + + <Card title="Use MCP" icon="plug" href="/docs/tutorials/use-remote-mcp-server"> + Connect to existing MCP servers and start using them + </Card> + + {" "} + + <Card title="Build Servers" icon="server" href="/quickstart/server"> + Create MCP servers to expose your data and tools + </Card> + + <Card title="Build Clients" icon="computer" href="/quickstart/client"> + Develop applications that connect to MCP servers + </Card> +</CardGroup> + +## Ready to Build? + +MCP provides official **SDKs** in multiple languages, see the [SDK documentation](/docs/sdk) to find the right SDK for your project. The SDKs handle the protocol details so you can focus on building your features. + + +# Architecture Overview +Source: https://modelcontextprotocol.io/docs/learn/architecture + + + +This overview of the Model Context Protocol (MCP) discusses its [scope](#scope) and [core concepts](#concepts-of-mcp), and provides an [example](#example) demonstrating each core concept. + +Because MCP SDKs abstract away many concerns, most developers will likely find the [data layer protocol](#data-layer-protocol) section to be the most useful. It discusses how MCP servers can provide context to an AI application. + +For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/sdk). + +## Scope + +The Model Context Protocol includes the following projects: + +* [MCP Specification](https://modelcontextprotocol.io/specification/latest): A specification of MCP that outlines the implementation requirements for clients and servers. +* [MCP SDKs](/docs/sdk): SDKs for different programming languages that implement MCP. +* **MCP Development Tools**: Tools for developing MCP servers and clients, including the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) +* [MCP Reference Server Implementations](https://github.com/modelcontextprotocol/servers): Reference implementations of MCP servers. + +<Note> + MCP focuses solely on the protocol for context exchange—it does not dictate + how AI applications use LLMs or manage the provided context. +</Note> + +## Concepts of MCP + +### Participants + +MCP follows a client-server architecture where an MCP host — an AI application like [Claude Code](https://www.anthropic.com/claude-code) or [Claude Desktop](https://www.claude.ai/download) — establishes connections to one or more MCP servers. The MCP host accomplishes this by creating one MCP client for each MCP server. Each MCP client maintains a dedicated one-to-one connection with its corresponding MCP server. + +The key participants in the MCP architecture are: + +* **MCP Host**: The AI application that coordinates and manages one or multiple MCP clients +* **MCP Client**: A component that maintains a connection to an MCP server and obtains context from an MCP server for the MCP host to use +* **MCP Server**: A program that provides context to MCP clients + +**For example**: Visual Studio Code acts as an MCP host. When Visual Studio Code establishes a connection to an MCP server, such as the [Sentry MCP server](https://docs.sentry.io/product/sentry-mcp/), the Visual Studio Code runtime instantiates an MCP client object that maintains the connection to the Sentry MCP server. +When Visual Studio Code subsequently connects to another MCP server, such as the [local filesystem server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), the Visual Studio Code runtime instantiates an additional MCP client object to maintain this connection, hence maintaining a one-to-one +relationship of MCP clients to MCP servers. + +```mermaid +graph TB + subgraph "MCP Host (AI Application)" + Client1["MCP Client 1"] + Client2["MCP Client 2"] + Client3["MCP Client 3"] + end + + Server1["MCP Server 1<br/>(e.g., Sentry)"] + Server2["MCP Server 2<br/>(e.g., Filesystem)"] + Server3["MCP Server 3<br/>(e.g., Database)"] + + Client1 ---|"One-to-one<br/>connection"| Server1 + Client2 ---|"One-to-one<br/>connection"| Server2 + Client3 ---|"One-to-one<br/>connection"| Server3 + + style Client1 fill:#e1f5fe + style Client2 fill:#e1f5fe + style Client3 fill:#e1f5fe + style Server1 fill:#f3e5f5 + style Server2 fill:#f3e5f5 + style Server3 fill:#f3e5f5 +``` + +Note that **MCP server** refers to the program that serves context data, regardless of +where it runs. MCP servers can execute locally or remotely. For example, when +Claude Desktop launches the [filesystem +server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), +the server runs locally on the same machine because it uses the STDIO +transport. This is commonly referred to as a "local" MCP server. The official +[Sentry MCP server](https://docs.sentry.io/product/sentry-mcp/) runs on the +Sentry platform, and uses the Streamable HTTP transport. This is commonly +referred to as a "remote" MCP server. + +### Layers + +MCP consists of two layers: + +* **Data layer**: Defines the JSON-RPC based protocol for client-server communication, including lifecycle management, and core primitives, such as tools, resources, prompts and notifications. +* **Transport layer**: Defines the communication mechanisms and channels that enable data exchange between clients and servers, including transport-specific connection establishment, message framing, and authorization. + +Conceptually the data layer is the inner layer, while the transport layer is the outer layer. + +#### Data layer + +The data layer implements a [JSON-RPC 2.0](https://www.jsonrpc.org/) based exchange protocol that defines the message structure and semantics. +This layer includes: + +* **Lifecycle management**: Handles connection initialization, capability negotiation, and connection termination between clients and servers +* **Server features**: Enables servers to provide core functionality including tools for AI actions, resources for context data, and prompts for interaction templates from and to the client +* **Client features**: Enables servers to ask the client to sample from the host LLM, elicit input from the user, and log messages to the client +* **Utility features**: Supports additional capabilities like notifications for real-time updates and progress tracking for long-running operations + +#### Transport layer + +The transport layer manages communication channels and authentication between clients and servers. It handles connection establishment, message framing, and secure communication between MCP participants. + +MCP supports two transport mechanisms: + +* **Stdio transport**: Uses standard input/output streams for direct process communication between local processes on the same machine, providing optimal performance with no network overhead. +* **Streamable HTTP transport**: Uses HTTP POST for client-to-server messages with optional Server-Sent Events for streaming capabilities. This transport enables remote server communication and supports standard HTTP authentication methods including bearer tokens, API keys, and custom headers. MCP recommends using OAuth to obtain authentication tokens. + +The transport layer abstracts communication details from the protocol layer, enabling the same JSON-RPC 2.0 message format across all transport mechanisms. + +### Data Layer Protocol + +A core part of MCP is defining the schema and semantics between MCP clients and MCP servers. Developers will likely find the data layer — in particular, the set of [primitives](#primitives) — to be the most interesting part of MCP. It is the part of MCP that defines the ways developers can share context from MCP servers to MCP clients. + +MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/) as its underlying RPC protocol. Client and servers send requests to each other and respond accordingly. Notifications can be used when no response is required. + +#### Lifecycle management + +MCP is a <Tooltip tip="A subset of MCP can be made stateless using the Streamable HTTP transport">stateful protocol</Tooltip> that requires lifecycle management. The purpose of lifecycle management is to negotiate the <Tooltip tip="Features and operations that a client or server supports, such as tools, resources, or prompts">capabilities</Tooltip> that both client and server support. Detailed information can be found in the [specification](/specification/2025-06-18/basic/lifecycle), and the [example](#example) showcases the initialization sequence. + +#### Primitives + +MCP primitives are the most important concept within MCP. They define what clients and servers can offer each other. These primitives specify the types of contextual information that can be shared with AI applications and the range of actions that can be performed. + +MCP defines three core primitives that *servers* can expose: + +* **Tools**: Executable functions that AI applications can invoke to perform actions (e.g., file operations, API calls, database queries) +* **Resources**: Data sources that provide contextual information to AI applications (e.g., file contents, database records, API responses) +* **Prompts**: Reusable templates that help structure interactions with language models (e.g., system prompts, few-shot examples) + +Each primitive type has associated methods for discovery (`*/list`), retrieval (`*/get`), and in some cases, execution (`tools/call`). +MCP clients will use the `*/list` methods to discover available primitives. For example, a client can first list all available tools (`tools/list`) and then execute them. This design allows listings to be dynamic. + +As a concrete example, consider an MCP server that provides context about a database. It can expose tools for querying the database, a resource that contains the schema of the database, and a prompt that includes few-shot examples for interacting with the tools. + +For more details about server primitives see [server concepts](./server-concepts). + +MCP also defines primitives that *clients* can expose. These primitives allow MCP server authors to build richer interactions. + +* **Sampling**: Allows servers to request language model completions from the client's AI application. This is useful when servers' authors want access to a language model, but want to stay model independent and not include a language model SDK in their MCP server. They can use the `sampling/complete` method to request a language model completion from the client's AI application. +* **Elicitation**: Allows servers to request additional information from users. This is useful when servers' authors want to get more information from the user, or ask for confirmation of an action. They can use the `elicitation/request` method to request additional information from the user. +* **Logging**: Enables servers to send log messages to clients for debugging and monitoring purposes. + +For more details about client primitives see [client concepts](./client-concepts). + +#### Notifications + +The protocol supports real-time notifications to enable dynamic updates between servers and clients. For example, when a server's available tools change—such as when new functionality becomes available or existing tools are modified—the server can send tool update notifications to inform connected clients about these changes. Notifications are sent as JSON-RPC 2.0 notification messages (without expecting a response) and enable MCP servers to provide real-time updates to connected clients. + +## Example + +### Data Layer + +This section provides a step-by-step walkthrough of an MCP client-server interaction, focusing on the data layer protocol. We'll demonstrate the lifecycle sequence, tool operations, and notifications using JSON-RPC 2.0 messages. + +<Steps> + <Step title="Initialization (Lifecycle Management)"> + MCP begins with lifecycle management through a capability negotiation handshake. As described in the [lifecycle management](#lifecycle-management) section, the client sends an `initialize` request to establish the connection and negotiate supported features. + + <CodeGroup> + ```json Request + { + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": { + "elicitation": {} + }, + "clientInfo": { + "name": "example-client", + "version": "1.0.0" + } + } + } + ``` + + ```json Response + { + "jsonrpc": "2.0", + "id": 1, + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "tools": { + "listChanged": true + }, + "resources": {} + }, + "serverInfo": { + "name": "example-server", + "version": "1.0.0" + } + } + } + ``` + </CodeGroup> + + #### Understanding the Initialization Exchange + + The initialization process is a key part of MCP's lifecycle management and serves several critical purposes: + + 1. **Protocol Version Negotiation**: The `protocolVersion` field (e.g., "2025-06-18") ensures both client and server are using compatible protocol versions. This prevents communication errors that could occur when different versions attempt to interact. If a mutually compatible version is not negotiated, the connection should be terminated. + + 2. **Capability Discovery**: The `capabilities` object allows each party to declare what features they support, including which [primitives](#primitives) they can handle (tools, resources, prompts) and whether they support features like [notifications](#notifications). This enables efficient communication by avoiding unsupported operations. + + 3. **Identity Exchange**: The `clientInfo` and `serverInfo` objects provide identification and versioning information for debugging and compatibility purposes. + + In this example, the capability negotiation demonstrates how MCP primitives are declared: + + **Client Capabilities**: + + * `"elicitation": {}` - The client declares it can work with user interaction requests (can receive `elicitation/create` method calls) + + **Server Capabilities**: + + * `"tools": {"listChanged": true}` - The server supports the tools primitive AND can send `tools/list_changed` notifications when its tool list changes + * `"resources": {}` - The server also supports the resources primitive (can handle `resources/list` and `resources/read` methods) + + After successful initialization, the client sends a notification to indicate it's ready: + + ```json Notification + { + "jsonrpc": "2.0", + "method": "notifications/initialized" + } + ``` + + #### How This Works in AI Applications + + During initialization, the AI application's MCP client manager establishes connections to configured servers and stores their capabilities for later use. The application uses this information to determine which servers can provide specific types of functionality (tools, resources, prompts) and whether they support real-time updates. + + ```python Pseudo-code for AI application initialization + # Pseudo Code + async with stdio_client(server_config) as (read, write): + async with ClientSession(read, write) as session: + init_response = await session.initialize() + if init_response.capabilities.tools: + app.register_mcp_server(session, supports_tools=True) + app.set_server_ready(session) + ``` + </Step> + + <Step title="Tool Discovery (Primitives)"> + Now that the connection is established, the client can discover available tools by sending a `tools/list` request. This request is fundamental to MCP's tool discovery mechanism — it allows clients to understand what tools are available on the server before attempting to use them. + + <CodeGroup> + ```json Request + { + "jsonrpc": "2.0", + "id": 2, + "method": "tools/list" + } + ``` + + ```json Response + { + "jsonrpc": "2.0", + "id": 2, + "result": { + "tools": [ + { + "name": "calculator_arithmetic", + "title": "Calculator", + "description": "Perform mathematical calculations including basic arithmetic, trigonometric functions, and algebraic operations", + "inputSchema": { + "type": "object", + "properties": { + "expression": { + "type": "string", + "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', 'sin(30)', 'sqrt(16)')" + } + }, + "required": ["expression"] + } + }, + { + "name": "weather_current", + "title": "Weather Information", + "description": "Get current weather information for any location worldwide", + "inputSchema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City name, address, or coordinates (latitude,longitude)" + }, + "units": { + "type": "string", + "enum": ["metric", "imperial", "kelvin"], + "description": "Temperature units to use in response", + "default": "metric" + } + }, + "required": ["location"] + } + } + ] + } + } + ``` + </CodeGroup> + + #### Understanding the Tool Discovery Request + + The `tools/list` request is simple, containing no parameters. + + #### Understanding the Tool Discovery Response + + The response contains a `tools` array that provides comprehensive metadata about each available tool. This array-based structure allows servers to expose multiple tools simultaneously while maintaining clear boundaries between different functionalities. + + Each tool object in the response includes several key fields: + + * **`name`**: A unique identifier for the tool within the server's namespace. This serves as the primary key for tool execution and should follow a clear naming pattern (e.g., `calculator_arithmetic` rather than just `calculate`) + * **`title`**: A human-readable display name for the tool that clients can show to users + * **`description`**: Detailed explanation of what the tool does and when to use it + * **`inputSchema`**: A JSON Schema that defines the expected input parameters, enabling type validation and providing clear documentation about required and optional parameters + + #### How This Works in AI Applications + + The AI application fetches available tools from all connected MCP servers and combines them into a unified tool registry that the language model can access. This allows the LLM to understand what actions it can perform and automatically generates the appropriate tool calls during conversations. + + ```python Pseudo-code for AI application tool discovery + # Pseudo-code using MCP Python SDK patterns + available_tools = [] + for session in app.mcp_server_sessions(): + tools_response = await session.list_tools() + available_tools.extend(tools_response.tools) + conversation.register_available_tools(available_tools) + ``` + </Step> + + <Step title="Tool Execution (Primitives)"> + The client can now execute a tool using the `tools/call` method. This demonstrates how MCP primitives are used in practice: after discovering available tools, the client can invoke them with appropriate arguments. + + #### Understanding the Tool Execution Request + + The `tools/call` request follows a structured format that ensures type safety and clear communication between client and server. Note that we're using the proper tool name from the discovery response (`weather_current`) rather than a simplified name: + + <CodeGroup> + ```json Request + { + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "weather_current", + "arguments": { + "location": "San Francisco", + "units": "imperial" + } + } + } + ``` + + ```json Response + { + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "Current weather in San Francisco: 68°F, partly cloudy with light winds from the west at 8 mph. Humidity: 65%" + } + ] + } + } + ``` + </CodeGroup> + + #### Key Elements of Tool Execution + + The request structure includes several important components: + + 1. **`name`**: Must match exactly the tool name from the discovery response (`weather_current`). This ensures the server can correctly identify which tool to execute. + + 2. **`arguments`**: Contains the input parameters as defined by the tool's `inputSchema`. In this example: + * `location`: "San Francisco" (required parameter) + * `units`: "imperial" (optional parameter, defaults to "metric" if not specified) + + 3. **JSON-RPC Structure**: Uses standard JSON-RPC 2.0 format with unique `id` for request-response correlation. + + #### Understanding the Tool Execution Response + + The response demonstrates MCP's flexible content system: + + 1. **`content` Array**: Tool responses return an array of content objects, allowing for rich, multi-format responses (text, images, resources, etc.) + + 2. **Content Types**: Each content object has a `type` field. In this example, `"type": "text"` indicates plain text content, but MCP supports various content types for different use cases. + + 3. **Structured Output**: The response provides actionable information that the AI application can use as context for language model interactions. + + This execution pattern allows AI applications to dynamically invoke server functionality and receive structured responses that can be integrated into conversations with language models. + + #### How This Works in AI Applications + + When the language model decides to use a tool during a conversation, the AI application intercepts the tool call, routes it to the appropriate MCP server, executes it, and returns the results back to the LLM as part of the conversation flow. This enables the LLM to access real-time data and perform actions in the external world. + + ```python + # Pseudo-code for AI application tool execution + async def handle_tool_call(conversation, tool_name, arguments): + session = app.find_mcp_session_for_tool(tool_name) + result = await session.call_tool(tool_name, arguments) + conversation.add_tool_result(result.content) + ``` + </Step> + + <Step title="Real-time Updates (Notifications)"> + MCP supports real-time notifications that enable servers to inform clients about changes without being explicitly requested. This demonstrates the notification system, a key feature that keeps MCP connections synchronized and responsive. + + #### Understanding Tool List Change Notifications + + When the server's available tools change—such as when new functionality becomes available, existing tools are modified, or tools become temporarily unavailable—the server can proactively notify connected clients: + + ```json Request + { + "jsonrpc": "2.0", + "method": "notifications/tools/list_changed" + } + ``` + + #### Key Features of MCP Notifications + + 1. **No Response Required**: Notice there's no `id` field in the notification. This follows JSON-RPC 2.0 notification semantics where no response is expected or sent. + + 2. **Capability-Based**: This notification is only sent by servers that declared `"listChanged": true` in their tools capability during initialization (as shown in Step 1). + + 3. **Event-Driven**: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive. + + #### Client Response to Notifications + + Upon receiving this notification, the client typically reacts by requesting the updated tool list. This creates a refresh cycle that keeps the client's understanding of available tools current: + + ```json Request + { + "jsonrpc": "2.0", + "id": 4, + "method": "tools/list" + } + ``` + + #### Why Notifications Matter + + This notification system is crucial for several reasons: + + 1. **Dynamic Environments**: Tools may come and go based on server state, external dependencies, or user permissions + 2. **Efficiency**: Clients don't need to poll for changes; they're notified when updates occur + 3. **Consistency**: Ensures clients always have accurate information about available server capabilities + 4. **Real-time Collaboration**: Enables responsive AI applications that can adapt to changing contexts + + This notification pattern extends beyond tools to other MCP primitives, enabling comprehensive real-time synchronization between clients and servers. + + #### How This Works in AI Applications + + When the AI application receives a notification about changed tools, it immediately refreshes its tool registry and updates the LLM's available capabilities. This ensures that ongoing conversations always have access to the most current set of tools, and the LLM can dynamically adapt to new functionality as it becomes available. + + ```python + # Pseudo-code for AI application notification handling + async def handle_tools_changed_notification(session): + tools_response = await session.list_tools() + app.update_available_tools(session, tools_response.tools) + if app.conversation.is_active(): + app.conversation.notify_llm_of_new_capabilities() + ``` + </Step> +</Steps> + + +# Client Concepts +Source: https://modelcontextprotocol.io/docs/learn/client-concepts + +Understanding MCP client concepts + +MCP clients are instantiated by host applications to communicate with particular MCP servers. The host application, like Claude.ai or an IDE, manages the overall user experience and coordinates multiple clients. Each client handles one direct communication with one server. + +Understanding the distinction is important: the *host* is the application users interact with, while *clients* are the protocol-level components that enable server connections. + +## Core Client Features + +In addition to making use of context provided by servers, clients may provide several features to servers. These client features allow server authors to build richer interactions. For example, clients can allow MCP servers to request additional information from the user via elicitations. Clients can offer the following capabilities: + +### Sampling + +Sampling allows servers to request language model completions through the client, enabling agentic behaviors while maintaining security and user control. + +#### Overview + +Sampling enables servers to perform AI-dependent tasks without directly integrating with or paying for AI models. Instead, servers can request that the client—which already has AI model access—handle these tasks on their behalf. This approach puts the client in complete control of user permissions and security measures. Because sampling requests occur within the context of other operations—like a tool analyzing data—and are processed as separate model calls, they maintain clear boundaries between different contexts, allowing for more efficient use of the context window. + +**Sampling flow:** + +```mermaid +sequenceDiagram + participant LLM + participant User + participant Client + participant Server + + Note over Server,Client: Server initiates sampling + Server->>Client: sampling/createMessage + + Note over Client,User: Human-in-the-loop review + Client->>User: Present request for approval + User-->>Client: Review and approve/modify + + Note over Client,LLM: Model interaction + Client->>LLM: Forward approved request + LLM-->>Client: Return generation + + Note over Client,User: Response review + Client->>User: Present response for approval + User-->>Client: Review and approve/modify + + Note over Server,Client: Complete request + Client-->>Server: Return approved response +``` + +The flow ensures security through multiple human-in-the-loop checkpoints. Users review and can modify both the initial request and the generated response before it returns to the server. + +**Request parameters example:** + +```typescript +{ + messages: [ + { + role: "user", + content: "Analyze these flight options and recommend the best choice:\n" + + "[47 flights with prices, times, airlines, and layovers]\n" + + "User preferences: morning departure, max 1 layover" + } + ], + modelPreferences: { + hints: [{ + name: "claude-3-5-sonnet" // Suggested model + }], + costPriority: 0.3, // Less concerned about API cost + speedPriority: 0.2, // Can wait for thorough analysis + intelligencePriority: 0.9 // Need complex trade-off evaluation + }, + systemPrompt: "You are a travel expert helping users find the best flights based on their preferences", + maxTokens: 1500 +} +``` + +#### Example: Flight Analysis Tool + +Consider a travel booking server with a tool called `findBestFlight` that uses sampling to analyze available flights and recommend the optimal choice. When a user asks "Book me the best flight to Barcelona next month," the tool needs AI assistance to evaluate complex trade-offs. + +The tool queries airline APIs and gathers 47 flight options. It then requests AI assistance to analyze these options: "Analyze these flight options and recommend the best choice: \[47 flights with prices, times, airlines, and layovers] User preferences: morning departure, max 1 layover." + +The client asks the user: "Allow sampling request?" Upon approval, the AI evaluates trade-offs—like cheaper red-eye flights versus convenient morning departures. The tool uses this analysis to present the top three recommendations. + +#### User Interaction Model + +Sampling is designed with human-in-the-loop control as a fundamental principle. Users maintain oversight through several mechanisms: + +**Approval controls**: Every sampling request needs explicit user consent. Clients show what the server wants to analyze and why. Users can approve, deny, or modify requests. + +**Transparency features**: Clients display the exact prompt, model selection, and token limits. Users review AI responses before they return to the server. + +**Configuration options**: Users can set model preferences, configure auto-approval for trusted operations, or require approval for everything. Clients may provide options to redact sensitive information. Users decide how much conversation context may be included in sampling requests through the `includeContext` parameter. + +**Isolation**: Sampling requests are isolated from the main conversation context by default. Servers cannot access user conversations. + +**Security considerations**: Both clients and servers must handle sensitive data appropriately during sampling. Clients should implement rate limiting and validate all message content. The human-in-the-loop design ensures that server-initiated AI interactions cannot compromise security or access sensitive data without explicit user consent. + +### Roots + +Roots define filesystem boundaries for server operations, allowing clients to specify which directories servers should focus on. + +#### Overview + +Roots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. Rather than giving servers unrestricted filesystem access, roots guide them to relevant working directories while maintaining security boundaries. + +**Root structure:** + +```json +{ + "uri": "file:///Users/agent/travel-planning", + "name": "Travel Planning Workspace" +} +``` + +Roots are exclusively filesystem paths and always use the `file://` URI scheme. They help servers understand project boundaries, workspace organization, and accessible directories. The roots list can be updated dynamically as users work with different projects or folders, with servers receiving notifications through `roots/list_changed` when boundaries change. + +It's important to note that while roots provide guidance to servers about where to operate, the client is always in full control of file access. Roots simply communicate intended boundaries—actual file access is always mediated by the client's security policies. + +#### Example: Travel Planning Workspace + +A travel agent working with multiple client trips benefits from roots to organize filesystem access. Consider a workspace with different directories for various aspects of travel planning. + +The client provides filesystem roots to the travel planning server: + +* `file:///Users/agent/travel-planning` - Main workspace containing all travel files +* `file:///Users/agent/travel-templates` - Reusable itinerary templates and resources +* `file:///Users/agent/client-documents` - Client passports and travel documents + +When the agent creates a Barcelona itinerary, the server works within these boundaries—accessing templates, saving the new itinerary, and referencing client documents. It cannot access files outside these roots. Servers typically access files within roots by using relative paths from the root directories or by utilizing file search tools that respect the root boundaries. + +If the agent opens an archive folder like `file:///Users/agent/archive/2023-trips`, the client updates the roots list via `roots/list_changed`. + +#### User Interaction Model + +Roots are typically managed automatically by host applications based on user actions, though some applications may expose manual root management: + +**Automatic root detection**: When users open folders, clients automatically expose them as roots. Opening a travel workspace gives servers access to itineraries and documents within that directory. + +**Manual root configuration**: Advanced users can specify roots through configuration. For example, adding `/travel-templates` for reusable resources while excluding directories with financial records. + +### Elicitation + +Elicitation enables servers to request specific information from users during interactions, creating more dynamic and responsive workflows. + +#### Overview + +Elicitation provides a structured way for servers to gather necessary information on demand. Instead of requiring all information up front or failing when data is missing, servers can pause their operations to request specific inputs from users. This creates more flexible interactions where servers adapt to user needs rather than following rigid patterns. + +**Elicitation flow:** + +```mermaid +sequenceDiagram + participant User + participant Client + participant Server + + Note over Server,Client: Server initiates elicitation + Server->>Client: elicitation/create + + Note over Client,User: Human interaction + Client->>User: Present elicitation UI + User-->>Client: Provide requested information + + Note over Server,Client: Complete request + Client-->>Server: Return user response + + Note over Server: Continue processing with new information +``` + +The flow enables dynamic information gathering. Servers can request specific data when needed, users provide information through appropriate UI, and servers continue processing with the newly acquired context. + +**Elicitation components example:** + +```typescript +{ + method: "elicitation/requestInput", + params: { + message: "Please confirm your Barcelona vacation booking details:", + schema: { + type: "object", + properties: { + confirmBooking: { + type: "boolean", + description: "Confirm the booking (Flights + Hotel = $3,000)" + }, + seatPreference: { + type: "string", + enum: ["window", "aisle", "no preference"], + description: "Preferred seat type for flights" + }, + roomType: { + type: "string", + enum: ["sea view", "city view", "garden view"], + description: "Preferred room type at hotel" + }, + travelInsurance: { + type: "boolean", + default: false, + description: "Add travel insurance ($150)" + } + }, + required: ["confirmBooking"] + } + } +} +``` + +#### Example: Holiday Booking Approval + +A travel booking server demonstrates elicitation's power through the final booking confirmation process. When a user has selected their ideal vacation package to Barcelona, the server needs to gather final approval and any missing details before proceeding. + +The server elicits booking confirmation with a structured request that includes the trip summary (Barcelona flights June 15-22, beachfront hotel, total \$3,000) and fields for any additional preferences—such as seat selection, room type, or travel insurance options. + +As the booking progresses, the server elicits contact information needed to complete the reservation. It might ask for traveler details for flight bookings, special requests for the hotel, or emergency contact information. + +#### User Interaction Model + +Elicitation interactions are designed to be clear, contextual, and respectful of user autonomy: + +**Request presentation**: Clients display elicitation requests with clear context about which server is asking, why the information is needed, and how it will be used. The request message explains the purpose while the schema provides structure and validation. + +**Response options**: Users can provide the requested information through appropriate UI controls (text fields, dropdowns, checkboxes), decline to provide information with optional explanation, or cancel the entire operation. Clients validate responses against the provided schema before returning them to servers. + +**Privacy considerations**: Elicitation never requests passwords or API keys. Clients warn about suspicious requests and let users review data before sending. + + +# Server Concepts +Source: https://modelcontextprotocol.io/docs/learn/server-concepts + +Understanding MCP server concepts + +MCP servers are programs that expose specific capabilities to AI applications through standardized protocol interfaces. Each server provides focused functionality for a particular domain. + +Common examples include file system servers for document management, email servers for message handling, travel servers for trip planning, and database servers for data queries. Each server brings domain-specific capabilities to the AI application. + +## Core Building Blocks + +Servers provide functionality through three building blocks: + +| Building Block | Purpose | Who Controls It | Real-World Example | +| -------------- | ------------------------- | ---------------------- | ------------------------------------------------------------ | +| **Tools** | For AI actions | Model-controlled | Search flights, send messages, create calendar events | +| **Resources** | For context data | Application-controlled | Documents, calendars, emails, weather data | +| **Prompts** | For interaction templates | User-controlled | "Plan a vacation", "Summarize my meetings", "Draft an email" | + +### Tools - AI Actions + +Tools enable AI models to perform actions through server-implemented functions. Each tool defines a specific operation with typed inputs and outputs. The model requests tool execution based on context. + +#### Overview + +Tools are schema-defined interfaces that LLMs can invoke. MCP uses JSON Schema for validation. Each tool performs a single operation with clearly defined inputs and outputs. Most importantly, tool execution requires explicit user approval, ensuring users maintain control over actions taken by a model. + +**Protocol operations:** + +| Method | Purpose | Returns | +| ------------ | ------------------------ | -------------------------------------- | +| `tools/list` | Discover available tools | Array of tool definitions with schemas | +| `tools/call` | Execute a specific tool | Tool execution result | + +**Example tool definition:** + +```typescript +{ + name: "searchFlights", + description: "Search for available flights", + inputSchema: { + type: "object", + properties: { + origin: { type: "string", description: "Departure city" }, + destination: { type: "string", description: "Arrival city" }, + date: { type: "string", format: "date", description: "Travel date" } + }, + required: ["origin", "destination", "date"] + } +} +``` + +#### Example: Taking Action + +Tools enable AI applications to perform actions on behalf of users. In a travel planning scenario, the AI application might use several tools to help book a vacation. + +First, it searches for flights using + +``` +searchFlights(origin: "NYC", destination: "Barcelona", date: "2024-06-15") +``` + +`searchFlights` queries multiple airlines and returns structured flight options. Once flights are selected, it creates a calendar event with + +``` +createCalendarEvent(title: "Barcelona Trip", startDate: "2024-06-15", endDate: "2024-06-22") +``` + +to mark the travel dates. Finally, it sends an out-of-office notification using + +``` +sendEmail(to: "team@work.com", subject: "Out of Office", body: "...") +``` + +to inform colleagues about the absence. + +Each tool execution requires explicit user approval, ensuring full control over actions taken. + +#### User Interaction Model + +Tools are model-controlled, meaning AI models can discover and invoke them automatically. However, MCP emphasizes human oversight through several mechanisms. Applications should clearly display available tools in the UI and provide visual indicators when tools are being considered or used. Before any tool execution, users must be presented with clear approval dialogs that explain exactly what the tool will do. + +For trust and safety, applications often enforce manual approval to give humans the ability to deny tool invocations. Applications typically implement this through approval dialogs, permission settings for pre-approving certain safe operations, and activity logs that show all tool executions with their results. + +### Resources - Context Data + +Resources provide structured access to information that the host application can retrieve and provide to AI models as context. + +#### Overview + +Resources expose data from files, APIs, databases, or any other source that an AI needs to understand context. Applications can access this information directly and decide how to use it - whether that's selecting relevant portions, searching with embeddings, or passing it all to the model. + +Resources use URI-based identification, with each resource having a unique URI such as `file:///path/to/document.md`. They declare MIME types for appropriate content handling and support two discovery patterns: **direct resources** with fixed URIs, and **resource templates** with parameterized URIs. + +**Resource Templates** enable dynamic resource access through URI templates. A template like `travel://activities/{city}/{category}` would access filtered activity data by substituting both `{city}` and `{category}` parameters. For example, `travel://activities/barcelona/museums` would return all museums in Barcelona. Resource Templates include metadata such as title, description, and expected MIME type, making them discoverable and self-documenting. + +**Protocol operations:** + +| Method | Purpose | Returns | +| -------------------------- | ------------------------------- | -------------------------------------- | +| `resources/list` | List available direct resources | Array of resource descriptors | +| `resources/templates/list` | Discover resource templates | Array of resource template definitions | +| `resources/read` | Retrieve resource contents | Resource data with metadata | +| `resources/subscribe` | Monitor resource changes | Subscription confirmation | + +#### Example: Accessing Context Data + +Continuing with the travel planning example, resources provide the AI application with access to relevant information: + +* **Calendar data** (`calendar://events/2024`) - To check availability +* **Travel documents** (`file:///Documents/Travel/passport.pdf`) - For important information +* **Previous itineraries** (`trips://history/barcelona-2023`) - User selects which past trip style to follow + +Instead of manually copying this information, resources provide raw information to AI applications. The application can choose how to best handle the data. Applications might choose to select a subset of data, using embeddings or keyword search, or pass the raw data from a resource directly to a model. In our example, during the planning phase, the AI application can pass the calendar data, weather data and travel preferences, so that the model can check availability, look up weather patterns, and reference travel preferences. + +**Resource Template Examples:** + +```json +{ + "uriTemplate": "weather://forecast/{city}/{date}", + "name": "weather-forecast", + "title": "Weather Forecast", + "description": "Get weather forecast for any city and date", + "mimeType": "application/json" +} + +{ + "uriTemplate": "travel://flights/{origin}/{destination}", + "name": "flight-search", + "title": "Flight Search", + "description": "Search available flights between cities", + "mimeType": "application/json" +} +``` + +These templates enable flexible queries. For weather data, users can access forecasts for any city/date combination. For flights, they can search routes between any two airports. When a user has input "NYC" as the `origin` airport and begins to input "Bar" as the `destination` airport, the system can suggest "Barcelona (BCN)" or "Barbados (BGI)". + +#### Parameter Completion + +Dynamic resources support parameter completion. For example: + +* Typing "Par" as input for `weather://forecast/{city}` might suggest "Paris" or "Park City" +* The system helps discover valid values without requiring exact format knowledge + +#### User Interaction Model + +Resources are application-driven, giving hosts flexibility in how they retrieve, process, and present available context. Common interaction patterns include tree or list views for browsing resources in familiar folder-like structures, search and filter interfaces for finding specific resources, automatic context inclusion based on heuristics or AI selection, and manual selection interfaces. + +Applications are free to implement resource discovery through any interface pattern that suits their needs. The protocol doesn't mandate specific UI patterns, allowing for resource pickers with preview capabilities, smart suggestions based on current conversation context, bulk selection for including multiple resources, or integration with existing file browsers and data explorers. + +### Prompts - Interaction Templates + +Prompts provide reusable templates. They allow MCP server authors to provide parameterized prompts for a domain, or showcase how to best use the MCP server. + +#### Overview + +Prompts are structured templates that define expected inputs and interaction patterns. They are user-controlled, requiring explicit invocation rather than automatic triggering. Prompts can be context-aware, referencing available resources and tools to create comprehensive workflows. Like resources, prompts support parameter completion to help users discover valid argument values. + +**Protocol operations:** + +| Method | Purpose | Returns | +| -------------- | -------------------------- | ------------------------------------- | +| `prompts/list` | Discover available prompts | Array of prompt descriptors | +| `prompts/get` | Retrieve prompt details | Full prompt definition with arguments | + +#### Example: Streamlined Workflows + +Prompts provide structured templates for common tasks. In the travel planning context: + +**"Plan a vacation" prompt:** + +```json +{ + "name": "plan-vacation", + "title": "Plan a vacation", + "description": "Guide through vacation planning process", + "arguments": [ + { "name": "destination", "type": "string", "required": true }, + { "name": "duration", "type": "number", "description": "days" }, + { "name": "budget", "type": "number", "required": false }, + { "name": "interests", "type": "array", "items": { "type": "string" } } + ] +} +``` + +Rather than unstructured natural language input, the prompt system enables: + +1. Selection of the "Plan a vacation" template +2. Structured input: Barcelona, 7 days, \$3000, \["beaches", "architecture", "food"] +3. Consistent workflow execution based on the template + +#### User Interaction Model + +Prompts are user-controlled, requiring explicit invocation. Applications typically expose prompts through various UI patterns such as slash commands (typing "/" to see available prompts like /plan-vacation), command palettes for searchable access, dedicated UI buttons for frequently used prompts, or context menus that suggest relevant prompts. + +The protocol gives implementers freedom to design interfaces that feel natural within their application. Key principles include easy discovery of available prompts, clear descriptions of what each prompt does, natural argument input with validation, and transparent display of the prompt's underlying template. + +## How It All Works Together + +The real power of MCP emerges when multiple servers work together, combining their specialized capabilities through a unified interface. + +### Example: Multi-Server Travel Planning + +Consider an AI application with three connected servers: + +1. **Travel Server** - Handles flights, hotels, and itineraries +2. **Weather Server** - Provides climate data and forecasts +3. **Calendar/Email Server** - Manages schedules and communications + +#### The Complete Flow + +1. **User invokes a prompt with parameters:** + + ```json + { + "prompt": "plan-vacation", + "arguments": { + "destination": "Barcelona", + "departure_date": "2024-06-15", + "return_date": "2024-06-22", + "budget": 3000, + "travelers": 2 + } + } + ``` + +2. **User selects resources to include:** + * `calendar://my-calendar/June-2024` (from Calendar Server) + * `travel://preferences/europe` (from Travel Server) + * `travel://past-trips/Spain-2023` (from Travel Server) + +3. **AI processes the request:** + + The AI first reads all selected resources to gather context. From the calendar, it identifies available dates. From travel preferences, it learns preferred airlines and hotel types. From past trips, it discovers previously enjoyed locations. From weather data, it checks climate conditions for the travel period. + + Using this context, the AI then requests user approval to execute a series of coordinated actions: searching for flights from NYC to Barcelona, finding hotels within the specified budget, creating a calendar event for the trip duration, and sending confirmation emails with the trip details. + + +# SDKs +Source: https://modelcontextprotocol.io/docs/sdk + +Official SDKs for building with the Model Context Protocol + +Build MCP servers and clients using our official SDKs. Choo [diff truncated]