mcpserver

README

mcpserver

Package mcpserver exposes the Graphplan solver as an MCP (Model Context Protocol) server over stdio. It provides both one-shot and stateful session-based planning tools.

Key Types

• Server -- the MCP server; created with NewServer
• ServerConfig -- settings such as max concurrent sessions

Tools

Tool	Description
solve_problem	Solve a one-shot planning problem (PDDL or JSON).
create_session	Create a named stateful planning session.
set_domain	Set the PDDL domain on a session.
set_problem	Set the PDDL problem on a session.
solve_session	Solve the problem stored in a session.
list_sessions	List all active session names.
delete_session	Delete a session by name.

Usage

solver, _ := graphplan.NewSolver(nil)
adapter := pddl.NewAdapter()

srv, err := mcpserver.NewServer(
    &mcpserver.ServerConfig{},
    solver, adapter, adapter,
)
if err != nil {
    log.Fatal(err)
}

if err := srv.Run(); err != nil {
    log.Fatal(err)
}

See cmd/gp-server/ for the production entrypoint.

Documentation

Overview

Package mcpserver exposes the Graphplan planner as an MCP server. It provides both one-shot and stateful session-based tools for defining domains, problems, and solving them via PDDL or JSON input formats.

Index

• Variables
• type DomainParser
• type Planner
• type ProblemParser
• type Server
  • func NewServer(cfg *ServerConfig, planner Planner, dParser DomainParser, ...) (*Server, error)
  • func (s *Server) HandleCreateSession(_ context.Context, req SessionRequest) error
  • func (s *Server) HandleDeleteSession(_ context.Context, req SessionRequest) error
  • func (s *Server) HandleListSessions(_ context.Context) []string
  • func (s *Server) HandleSetDomain(_ context.Context, req SetDomainRequest) error
  • func (s *Server) HandleSetProblem(_ context.Context, req SetProblemRequest) error
  • func (s *Server) HandleSolveProblem(_ context.Context, req SolveProblemRequest) (*SolveResponse, error)
  • func (s *Server) HandleSolveSession(_ context.Context, req SessionRequest) (*SolveResponse, error)
  • func (s *Server) Run() error
• type ServerConfig
• type Session
• type SessionRequest
• type SessionStore
  • func NewSessionStore(capacity int) *SessionStore
  • func (s *SessionStore) Create(name string) error
  • func (s *SessionStore) Delete(name string) error
  • func (s *SessionStore) Get(name string) (*Session, error)
  • func (s *SessionStore) List() []string
• type SetDomainRequest
• type SetProblemRequest
• type SolveProblemRequest
• type SolveResponse
• type StepJSON

Variables

var (
	// ErrSessionExists indicates a session with that
	// name already exists.
	ErrSessionExists = errors.New(
		"session already exists",
	)

	// ErrSessionNotFound indicates no session with
	// that name was found.
	ErrSessionNotFound = errors.New(
		"session not found",
	)

	// ErrMaxSessions indicates the session limit has
	// been reached.
	ErrMaxSessions = errors.New(
		"maximum sessions reached",
	)
)

Types

type DomainParser

type DomainParser interface {
	// ParseDomain parses a PDDL domain string.
	ParseDomain(
		input string,
	) (*graphplan.Domain, error)
}

DomainParser parses domain definitions from PDDL.

type Planner

type Planner interface {
	// Solve finds a plan for the given problem.
	Solve(
		p *graphplan.Problem,
	) ([]graphplan.PlanStep, error)
}

Planner solves STRIPS planning problems.

type ProblemParser

type ProblemParser interface {
	// ParseProblem parses a PDDL problem string.
	ParseProblem(
		input string,
		domain *graphplan.Domain,
	) (*graphplan.Problem, error)
}

ProblemParser parses problem definitions from PDDL.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the MCP server exposing Graphplan tools.

Pattern: Facade -- hides planner/parser coordination behind MCP tool endpoints.

func NewServer

func NewServer(
	cfg *ServerConfig,
	planner Planner,
	dParser DomainParser,
	pParser ProblemParser,
) (*Server, error)

NewServer creates and configures the MCP server with all tools registered.

func (*Server) HandleCreateSession

func (s *Server) HandleCreateSession(
	_ context.Context,
	req SessionRequest,
) error

HandleCreateSession creates a new named session.

func (*Server) HandleDeleteSession

func (s *Server) HandleDeleteSession(
	_ context.Context,
	req SessionRequest,
) error

HandleDeleteSession removes a session by name.

func (*Server) HandleListSessions

func (s *Server) HandleListSessions(
	_ context.Context,
) []string

HandleListSessions returns all session names.

func (*Server) HandleSetDomain

func (s *Server) HandleSetDomain(
	_ context.Context,
	req SetDomainRequest,
) error

HandleSetDomain parses and sets a domain on a session.

func (*Server) HandleSetProblem

func (s *Server) HandleSetProblem(
	_ context.Context,
	req SetProblemRequest,
) error

HandleSetProblem parses and sets a problem on a session.

func (*Server) HandleSolveProblem

func (s *Server) HandleSolveProblem(
	_ context.Context,
	req SolveProblemRequest,
) (*SolveResponse, error)

HandleSolveProblem solves a one-shot problem.

func (*Server) HandleSolveSession

func (s *Server) HandleSolveSession(
	_ context.Context,
	req SessionRequest,
) (*SolveResponse, error)

HandleSolveSession solves the problem stored in a session.

func (*Server) Run

func (s *Server) Run() error

Run starts the MCP server over stdio.

type ServerConfig

type ServerConfig struct {
	// MaxSessions caps concurrent stateful sessions.
	// Nil defaults to 16.
	MaxSessions *int `json:"max_sessions,omitempty" yaml:"max_sessions"`
	// Version is reported to MCP clients. Defaults to
	// "dev" if empty.
	Version string `json:"version,omitempty" yaml:"version"`
}

ServerConfig controls MCP server behavior.

type Session

type Session struct {
	Domain  *graphplan.Domain
	Problem *graphplan.Problem
	Name    string
}

Session holds the state for a stateful planning session.

type SessionRequest

type SessionRequest struct {
	Name string `json:"name"`
}

SessionRequest identifies a session by name.

type SessionStore

type SessionStore struct {
	// contains filtered or unexported fields
}

SessionStore manages named sessions with a maximum capacity.

func NewSessionStore

func NewSessionStore(
	capacity int,
) *SessionStore

NewSessionStore creates a store with the given capacity.

func (*SessionStore) Create

func (s *SessionStore) Create(name string) error

Create adds a new empty session.

func (*SessionStore) Delete

func (s *SessionStore) Delete(name string) error

Delete removes a session by name.

func (*SessionStore) Get

func (s *SessionStore) Get(
	name string,
) (*Session, error)

Get returns the session with the given name.

func (*SessionStore) List

func (s *SessionStore) List() []string

List returns all session names, sorted.

type SetDomainRequest

type SetDomainRequest struct {
	Session string `json:"session"`
	Domain  string `json:"domain"`
}

SetDomainRequest sets the domain on a session.

type SetProblemRequest

type SetProblemRequest struct {
	Session string `json:"session"`
	Problem string `json:"problem"`
}

SetProblemRequest sets the problem on a session.

type SolveProblemRequest

type SolveProblemRequest struct {
	Format  string `json:"format"`
	Domain  string `json:"domain"`
	Problem string `json:"problem"`
}

SolveProblemRequest is the typed input for solve_problem.

type SolveResponse

type SolveResponse struct {
	Error    string     `json:"error,omitempty"`
	Steps    []StepJSON `json:"steps,omitempty"`
	Solvable bool       `json:"solvable"`
}

SolveResponse is the result of solving a problem.

type StepJSON

type StepJSON struct {
	Actions []string `json:"actions"`
	Time    int      `json:"time"`
}

StepJSON is one time step in the plan output.