nestrs-mcp: Model Context Protocol server

# Cargo.toml
[dependencies]
nestrs-mcp = "1.5.0"

# Or pull in the optional features:
# nestrs-mcp = { version = "1.5.0", features = ["http", "admin", "authz", "elicitation"] }

pub mod docs;            // local-file docs search (CHANGELOG, mdBook, READMEs)
pub mod error;           // crate Error + Result
pub mod introspection;   // source-level + live-registry snapshot
#[cfg(feature = "authz")]
pub mod mcp_data_context; // McpDataContext + per-tool-call authz scopes
pub mod runtime;         // HTTP client for the live admin port (AdminClient)
pub mod scaffold;        // new_project / create_module / create_resource / create_dto / generate_crud
pub mod server;          // NestrsMcpServer + SubServers
pub mod surfaces;        // McpSurfaces: prompts, resources, templates, completion, subscriptions
pub mod tools;           // IntrospectionTools / RuntimeTools / ScaffoldTools / DocsTools
pub mod wizard;          // init/setup editor config writer

use nestrs_mcp::{assistant_text, elicit_input, input_responses, text_contents,
                 user_text, CacheHints, Error, McpSurfaces, Result};
// server::NestrsMcpServer is NOT re-exported at the root:
use nestrs_mcp::server::NestrsMcpServer;

#[cfg(feature = "admin")]       // re-export from the nestrs crate
use nestrs_mcp::{AdminHandle, AdminOptions};
#[cfg(feature = "authz")]
use nestrs_mcp::{current_mcp_ability, current_mcp_transaction, McpDataContext};
#[cfg(feature = "elicitation")]
use nestrs_mcp::ElicitationHandler;

nestrs-mcp --help

Run as an MCP server over stdio (default) or HTTP, or run `init`/`setup` to detect installed editors and write the right config files for the `nestrs` server.

Usage: nestrs-mcp [OPTIONS] [COMMAND]

Commands:
  init   Detect installed editors and write the nestrs MCP config into each one
  setup  Alias for `init` (matches the post-install UX verb used in the docs)
  help   Print this message or the help of the given subcommand(s)

Options:
      --transport <TRANSPORT>
          Transport for the server mode (no subcommand). Ignored when a subcommand is given

          [default: stdio]
          [possible values: stdio, http]

      --http-addr <HTTP_ADDR>
          HTTP listen address for the server mode. Required when `--transport http`. Ignored otherwise

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

use nestrs_mcp::server::{NestrsMcpServer, SubServers};
use rmcp::task_manager::{TaskContext, TaskFuture, TaskManager, TaskOptions};
use rmcp::model::{ElicitRequestParams, ElicitResult, Task};
use rmcp::service::{RequestContext, RoleServer};

pub struct NestrsMcpServer {
    pub tool_router: ToolRouter<Self>,
    #[cfg(feature = "authz")]
    pub data_context: McpDataContext,
    pub surfaces: McpSurfaces,
    // private: tasks (TaskManager), task_support (bool)
}

impl NestrsMcpServer {
    pub fn new() -> Self;

    /// Attach prompts / resources / templates / completion. The server clones
    /// the inner Arc, so registrations added to the same McpSurfaces after
    /// with_surfaces are visible on the server.
    pub fn with_surfaces(mut self, surfaces: McpSurfaces) -> Self;

    /// Advertise the SEP-2663 tasks extension (tasks/get, tasks/update,
    /// tasks/cancel) in get_info. The TaskManager exists either way.
    pub fn with_task_support(mut self) -> Self;

    /// The task store backing the SEP-2663 extension.
    pub fn tasks(&self) -> &TaskManager;

    /// Spawn an operation as a task and return its seed Task state for a
    /// CreateTaskResult. The future must be 'static — move owned data in.
    pub fn spawn_task(
        &self,
        options: TaskOptions,
        make_future: impl FnOnce(TaskContext) -> TaskFuture,
    ) -> Task;

    #[cfg(feature = "authz")]
    pub fn with_data_context(mut self, ctx: McpDataContext) -> Self;

    #[cfg(feature = "elicitation")]
    pub async fn elicit(
        &self,
        request: ElicitRequestParams,
        context: RequestContext<RoleServer>,
    ) -> Result<ElicitResult, rmcp::ErrorData>;

    /// All four area handlers, each a full ServerHandler.
    pub fn sub_servers() -> SubServers;
}

pub struct SubServers {
    pub introspection: IntrospectionTools, // nestrs_mcp::tools::introspection
    pub runtime: RuntimeTools,              // nestrs_mcp::tools::runtime
    pub scaffold: ScaffoldTools,           // nestrs_mcp::tools::scaffold
    pub docs: DocsTools,                   // nestrs_mcp::tools::docs
}

use rmcp::handler::server::wrapper::Parameters;
use rmcp::{tool, tool_handler, tool_router, ErrorData, Json};

#[derive(Debug)]
pub struct MyTools;

#[tool_router]
impl MyTools {
    #[tool(
        name = "get_widget",
        description = "Fetch one widget.",
        annotations(read_only_hint = true)
    )]
    pub async fn get_widget(
        &self,
        Parameters(args): Parameters<WidgetArgs>, // WidgetArgs: Deserialize + JsonSchema
    ) -> Result<Json<serde_json::Value>, ErrorData> {
        Ok(Json(serde_json::json!({ "id": args.id })))
    }
}

#[tool_handler]
impl MyTools {}

use nestrs_mcp::McpSurfaces;

impl McpSurfaces {
    pub fn new() -> Self;

    pub fn register_prompt<H>(
        self,
        name: impl Into<String>,
        description: Option<String>,
        arguments: Vec<PromptArgument>,
        handler: H,
    ) -> Self
    where
        H: Fn(serde_json::Map<String, serde_json::Value>)
                -> Result<Vec<PromptMessage>, String>
            + Send + Sync + 'static;

    pub fn register_resource<H>(self, resource: Resource, handler: H) -> Self
    where
        H: Fn(&str) -> Result<Vec<ResourceContents>, String> + Send + Sync + 'static;

    /// The handler receives the *expanded* URI (the client expands the
    /// RFC 6570 template itself, then calls resources/read).
    pub fn register_resource_template<H>(self, template: ResourceTemplate, handler: H) -> Self
    where
        H: Fn(&str) -> Result<Vec<ResourceContents>, String> + Send + Sync + 'static;

    /// One completion handler for the whole server (the protocol has a
    /// single completion/complete endpoint; the handler reads the
    /// request's `ref` to disambiguate).
    pub fn register_complete<H>(self, handler: H) -> Self
    where
        H: Fn(&str, &CompleteRequestParams) -> Result<Vec<String>, String>
            + Send + Sync + 'static;

    /// Mark a URI eligible for subscription. Only then does get_info
    /// advertise `resources.subscribe`.
    pub fn register_subscribable_resource(self, uri: impl Into<String>) -> Self;

    #[cfg(feature = "elicitation")]
    pub fn register_elicitation<H>(self, handler: H) -> Self
    where
        H: Fn(
                ElicitRequestParams,
                RequestContext<RoleServer>,
            ) -> Result<ElicitResult, String>
            + Send + Sync + 'static;

    /// SEP-2549 cache hints on every list/read result — emitted only to
    /// peers on protocol >= 2026-07-28.
    pub fn with_cache_hints(self, hints: CacheHints) -> Self;
}

pub type PromptHandler =
    Box<dyn Fn(serde_json::Map<String, serde_json::Value>)
        -> Result<Vec<PromptMessage>, String> + Send + Sync + 'static>;
pub type ResourceHandler =
    Box<dyn Fn(&str) -> Result<Vec<ResourceContents>, String> + Send + Sync + 'static>;
pub type ResourceTemplateHandler =
    Box<dyn Fn(&str) -> Result<Vec<ResourceContents>, String> + Send + Sync + 'static>;
pub type CompleteHandler =
    Box<dyn Fn(&str, &CompleteRequestParams) -> Result<Vec<String>, String>
        + Send + Sync + 'static>;
#[cfg(feature = "elicitation")]
pub type ElicitationHandler =
    Arc<dyn Fn(ElicitRequestParams, RequestContext<RoleServer>)
        -> Result<ElicitResult, String> + Send + Sync + 'static>;

use rmcp::model::CacheScope; // Public (default) | Private

pub struct CacheHints {
    pub ttl_ms: u64,             // how long the client may cache, in ms
    pub cache_scope: CacheScope,
}
impl CacheHints {
    pub fn new(ttl_ms: u64, cache_scope: CacheScope) -> Self;
}

pub fn user_text(text: impl Into<String>) -> PromptMessage;        // Role::User
pub fn assistant_text(text: impl Into<String>) -> PromptMessage;  // Role::Assistant
pub fn text_contents(
    uri: impl Into<String>,
    mime_type: Option<impl Into<String>>,  // e.g. Some("text/markdown")
    text: impl Into<String>,
) -> ResourceContents;

pub fn elicit_input(
    message: impl Into<String>,
    schema: ElicitationSchema,
    request_state: Option<String>,   // opaque state carried across rounds
) -> InputRequiredResult;

/// Extract the `inputResponses` the client echoed back on the retried
/// tools/call. None means "no prior round."
pub fn input_responses(
    request: &CallToolRequestParams,
) -> Option<BTreeMap<String, serde_json::Value>>;

#[cfg(feature = "elicitation")]
pub async fn elicit(
    &self,
    request: ElicitRequestParams,
    context: RequestContext<RoleServer>,
) -> Result<ElicitResult, rmcp::ErrorData>;

let task = server.spawn_task(TaskOptions::default(), |ctx| {
    Box::pin(async move {
        // ctx.cancelled() -> cooperative cancel (return Err(TaskExit::Cancelled))
        // ctx.request_input(key, request).await -> mid-flight MRTR round
        Ok(CallToolResult::success(vec![ContentBlock::text("done")]))
    })
});

pub struct McpDataContext {
    pub ability: Option<Arc<nestrs::Ability>>,
    pub pool: Option<Arc<sqlx::AnyPool>>,
    pub principal: Option<Arc<nestrs::policies::Principal>>,
}

impl McpDataContext {
    pub fn new() -> Self;
    pub fn with_ability(mut self, a: Arc<Ability>) -> Self;
    pub fn with_pool(mut self, p: Arc<sqlx::AnyPool>) -> Self;
    pub fn with_principal(mut self, p: Arc<nestrs::policies::Principal>) -> Self;
}

pub fn current_mcp_ability() -> Option<Arc<Ability>>;              // re-exported at root
pub fn current_mcp_transaction() -> Option<Arc<TransactionSlot>>; // re-exported at root
// module path only (not re-exported at the root):
pub fn nestrs_mcp::mcp_data_context::current_mcp_principal()
    -> Option<Arc<nestrs::policies::Principal>>;

pub async fn run_with_mcp_scopes<F, T>(
    data_context: &McpDataContext,
    slot: Option<Arc<TransactionSlot>>,
    dispatch: F,
) -> T
where
    F: Future<Output = T>;

pub fn mask_response(resp: &mut CallToolResponse, ability: &Ability);
pub fn is_tool_error(resp: &CallToolResponse) -> bool;
pub async fn commit_or_rollback(slot: Option<Arc<TransactionSlot>>, resp: &CallToolResponse);
pub fn install_tx_slot_in_scope(slot: Arc<TransactionSlot>);

use nestrs_mcp::runtime::AdminClient;

let client = AdminClient::new("http://127.0.0.1:7777", Some("token".into()))?;
let health = client.health().await?;
let routes = client.routes().await?;
let providers = client.providers().await?;

pub struct AdminHealth { pub status: String, pub uptime_ms: u64, pub version: String }
pub struct AdminProviders(pub Vec<LiveProviderSummary>);  // transparent serde
pub struct AdminRoutes(pub Vec<LiveRouteSummary>);        // transparent serde

// nestrs_mcp::introspection::registry
pub struct LiveRouteSummary {
    pub method: String,
    pub path: String,
    pub handler: String,              // module_path::handler
    pub openapi_summary: Option<String>,
}
pub struct LiveProviderSummary {
    pub type_name: String,
    pub scope: String,                // "singleton" | "transient" | "request"
}

pub enum SnapshotError {
    Http { status: u16, body: String },
    Parse(serde_json::Error),
    MissingField(&'static str),
}

// nestrs_mcp::introspection
pub fn parse_workspace(path: &Path) -> Result<ParsedWorkspace>;

pub struct SourceParser { /* root: PathBuf */ }
impl SourceParser {
    /// Errors if the path doesn't exist, isn't a directory,
    /// or has no Cargo.toml.
    pub fn new(root: impl AsRef<Path>) -> Result<Self, SourceParserError>;
    pub fn parse(&self) -> Result<ParsedWorkspace, SourceParserError>;
}

pub struct ParsedWorkspace {
    pub root: PathBuf,
    pub modules: Vec<ModuleSummary>,
    pub controllers: Vec<ControllerSummary>,
    pub providers: Vec<ProviderSummary>,
    pub dtos: Vec<DtoSummary>,
    pub schedules: Vec<String>,
    pub event_handlers: Vec<String>,
    pub queue_processors: Vec<String>,
    pub stats: WorkspaceStats,
    pub warnings: Vec<ParserWarning>,
}

pub struct ModuleSummary {
    pub name: String,
    pub file: String,
    pub imports: Vec<String>,
    pub controllers: Vec<String>,
    pub providers: Vec<String>,
    pub microservices: Vec<String>,
    pub exports: Vec<String>,
    pub re_exports: Vec<String>,
}

pub struct ControllerSummary {
    pub name: String,
    pub module_path: String,          // e.g. "myapp::users", inferred from the file
    pub file: String,
    pub prefix: Option<String>,        // from #[controller("/users")]
    pub version: Option<String>,
    pub host: Option<String>,
    pub routes: Vec<RouteSummary>,
    pub controller_guards: Vec<String>, // from #[routes(controller_guards = (...))]
    pub state: Option<String>,         // from #[routes(state = T)]
}

pub struct ProviderSummary {
    pub type_name: String,
    pub file: String,
    pub scope: Option<String>,        // "singleton" | "transient" | "request"
    pub is_injectable: bool,
}

pub struct RouteSummary {
    pub method: String,
    pub path: String,
    pub handler: String,
    pub version: Option<String>,
    pub guards: Vec<String>,
    pub interceptors: Vec<String>,
    pub pipes: Vec<String>,
    pub filters: Vec<String>,
    pub metadata: BTreeMap<String, String>,
    pub body_type: Option<String>,      // e.g. "ValidatedBody<CreateUserDto>"
    pub response_type: Option<String>,  // inferred from the handler's return type
}

pub struct WorkspaceStats {
    pub files_scanned: usize,
    pub modules: usize,
    pub controllers: usize,
    pub providers: usize,
    pub routes: usize,
    pub dtos: usize,
    pub warnings: usize,
}

pub struct ParserWarning {
    pub file: String,
    pub line: usize,
    pub kind: String,
    pub message: String,
}

#[derive(Debug, thiserror::Error)]
pub enum SourceParserError {
    WorkspaceNotFound(PathBuf),
    NotADirectory(PathBuf),
    NoCargoToml(PathBuf),
    Io { path: PathBuf, source: std::io::Error },
    Syn { file: String, message: String },
}

pub struct DtoSummary {
    pub name: String,
    pub module_path: String,
    pub file: String,
    pub field_count: usize,
    pub allow_unknown_fields: bool, // #[dto(allow_unknown_fields)]
    pub expose_only: bool,          // #[dto(expose_only)]
}

pub struct DtoField {
    pub name: String,
    pub ty: String,       // e.g. "String", "Option<i64>" — generics kept as one string
    pub optional: bool,
    pub validators: Vec<Validator>,
}

// Serde shape: {"kind": "min_length", "value": 3} etc. (tag = "kind", snake_case)
pub enum Validator {
    IsString, IsEmail, IsNotEmpty, IsUuid, IsPositive, IsNegative, IsInt,
    IsNumber, IsBoolean, IsUrl, IsOptional, ValidateNested, Expose, Exclude,
    MinLength { value: u64 },
    MaxLength { value: u64 },
    Length { min: u64, max: u64 },
    Min { value: String },
    Max { value: String },
    Matches { pattern: String },
    Contains { substring: String },
    Unknown { name: String, args: String }, // surfaced, never silently dropped
}

// nestrs_mcp::scaffold
pub fn new_project(path: &Path, name: &str, transports: &[String]) -> Result<ScaffoldReport>;
pub fn create_module(path: &Path, name: &str, _transports: &[String]) -> Result<ScaffoldReport>;
pub fn create_resource(
    path: &Path,
    name: &str,
    dto_fields: &[DtoFieldSpec],
    transport: ResourceTransport,
) -> Result<ScaffoldReport>;
pub fn create_dto(path: &Path, name: &str, fields: &[DtoFieldSpec]) -> Result<ScaffoldReport>;
pub fn generate_crud(path: &Path, spec: &CrudSpec) -> Result<ScaffoldReport>;

pub struct ScaffoldReport {
    pub files_created: Vec<String>,
    pub files_modified: Vec<String>,
}

pub struct DtoFieldSpec {
    pub name: String,
    pub ty: String,           // e.g. "String", "Option<i64>"
    pub optional: bool,
    pub validators: Vec<String>,
}

#[serde(rename_all = "snake_case")]  // "http" | "graphql" | "ws" | "tcp" on the wire
pub enum ResourceTransport { Http, Graphql, Ws, Tcp }

pub struct CrudSpec {
    pub resource: String,
    pub fields: Vec<DtoFieldSpec>,
    pub transports: Vec<ResourceTransport>,
}

// nestrs_mcp::docs
pub struct DocStore { /* RwLock inner */ }
impl DocStore {
    pub fn new() -> Self;
    /// Index CHANGELOG.md + docs/src/**/*.md + **/README.md under root.
    /// Returns the number of files indexed.
    pub fn build(&self, root: &Path) -> crate::Result<usize>;
    pub fn sources(&self) -> Vec<DocSource>;
    pub fn file_count(&self) -> usize;
}

pub struct DocSource {
    pub path: PathBuf,
    pub kind: DocKind,     // Changelog | Book | Readme | Other
    pub bytes: usize,
    pub content: String,
}

pub fn changelog_entries(source: &DocSource) -> Vec<ChangelogEntry>;
pub struct ChangelogEntry { pub version: String, pub date: String }

pub struct DocSearcher;
impl DocSearcher {
    pub fn search(
        sources: &[DocSource],
        query: &str,
        scope: SearchScope,   // Changelog | Book | Readme | All
        limit: usize,
    ) -> Vec<DocHit>;
}

pub struct DocHit {
    pub path: String,
    pub kind: String,
    pub score: f64,
    pub context: Vec<String>, // up to 3 lines: match + one before + one after
}

// nestrs_mcp::wizard
pub const DEFAULT_HTTP_ADDR: &str = "127.0.0.1:7777";

pub struct InitArgs {
    pub yes: bool,
    pub no_interactive: bool,
    pub transport: WizardTransport,   // Stdio | Http
    pub http_addr: Option<String>,
    pub start_http_server: bool,
}

pub fn run(args: InitArgs) -> anyhow::Result<WizardOutcome>;

impl WizardTransport {
    /// The JSON value for the nestrs server entry, given the HTTP URL
    /// (used only when self == Http).
    pub fn server_value(self, http_url: &str) -> ServerValue;
}

/// Either a JSON object (Claude Code / Cursor / VS Code) or a TOML
/// inline table (Codex).
pub enum ServerValue { Json(serde_json::Value), Toml(toml::Value) }

pub struct WizardOutcome {
    pub selected: Vec<Editor>,
    pub written: Vec<WriteResult>,
    pub transport: WizardTransport,
    pub server_pid: Option<u32>,
    pub server_url: Option<String>,     // http://<addr>/mcp when spawned
    /// The spawned server's child handle, kept alive for the wizard's
    /// lifetime (None unless --start-http-server was given).
    pub _server: Option<spawn::SpawnedServer>,
    pub dry_run: bool,
}

pub struct WriteResult {
    pub editor: Editor,
    pub path: PathBuf,
    pub outcome: WriteOutcome,          // Created | Added | Updated | NoChange
}

pub enum Editor {
    ClaudeCodeProject,  // ./.mcp.json            (mcpServers)
    ClaudeCodeGlobal,   // ~/.claude.json         (mcpServers)
    Cursor,             // ~/.cursor/mcp.json     (mcpServers)
    VsCodeCopilot,      // ./.vscode/mcp.json     (servers)
    Codex,              // ~/.codex/config.toml  ([mcp_servers])
}
impl Editor {
    pub const fn all() -> [Editor; 5];
    pub fn path(self, cwd: &Path) -> anyhow::Result<PathBuf>;
    pub fn top_level_key(self) -> &'static str;
    pub fn toml_table(self) -> &'static str;
    pub fn is_toml(self) -> bool;
    pub fn label(self) -> &'static str;
}

pub enum Error {
    Io(std::io::Error),
    Parse(String),
    WorkspaceNotFound(String),
    FileNotFound(String),
    InvalidArgument(String),
    Scaffold(String),
    Docs(String),
    Network(String),
    Admin(String),
    Other(anyhow::Error),
}
pub type Result<T> = std::result::Result<T, Error>;

use nestrs_mcp::server::NestrsMcpServer;
use nestrs_mcp::tools::introspection::IntrospectionTools;
use rmcp::service::serve_server;
use rmcp::transport::stdio;

// Option A: one area's tools on stdio
let running = serve_server(IntrospectionTools, stdio()).await?;

// Option B: the wrapper (surfaces / tasks / authz; no tools)
let server = NestrsMcpServer::new()
    .with_surfaces(surfaces)
    .with_task_support();
let running = serve_server(server, stdio()).await?;