feat: add environment, project, and profile support (#26)

* feat: add environment, project, and profile support

Add Environment and Project models to core SDK with list/get API methods.
Add list_profiles endpoint supporting workspace, deployment, or project+branch targeting.

New CLI subcommands: environment (list/get), project (list/get), profile (list).
New MCP tools: list_environments, list_projects, list_profiles.
New Python SDK methods: list_environments, get_environment, list_projects,
get_project, list_profiles.

Update type stubs, docs, and skill files for all three interfaces.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add get_environment and get_project MCP tools, update AGENTS.md

Add missing get_environment and get_project MCP tools with
GetEnvironmentParams and GetProjectParams, matching the CLI and Python
SDK which already had these. Update AGENTS.md tool count (18→23),
tool table, CLI reference, Python SDK reference, and backend API table
to reflect all environment/project/profile additions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: format

* fix: validate list_profiles params, rename test, add missing docs

- MCP: require branch when project is provided in list_profiles
- Python: require branch with project and at least one selector in list_profiles
- Rename misleading test_cli_parses_environment_default_is_list
- Add list_profiles examples to docs/python.md and skill-py.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lostmygithubaccount

AGENTS.md

@@ -28,7 +28,7 @@ src/ascend_tools/
 ├── ascend-tools-mcp/          # MCP server crate (depends on ascend-tools-core)
 │   └── src/
 │       ├── lib.rs           # run_stdio() and run_http() entry points
-│       ├── server.rs        # AscendMcpServer — 18 tools via rmcp #[tool_router]
+│       ├── server.rs        # AscendMcpServer — 23 tools via rmcp #[tool_router]
 │       └── params.rs        # typed parameter structs with JsonSchema for MCP tool schemas
 │
 ├── ascend-tools-cli/          # Rust CLI crate (depends on ascend-tools-core, ascend-tools-mcp)
@@ -117,6 +117,14 @@ ascend-tools [-o text|json] [-V]
   deployment resume-automations <TITLE>
   deployment delete <TITLE>
 
+  environment list
+  environment get <TITLE>
+
+  project list
+  project get <TITLE>
+
+  profile list --workspace <TITLE> | --deployment <TITLE> | --project <NAME> --git-branch <BRANCH>
+
   flow list --workspace <TITLE> | --deployment <TITLE>
   flow run <FLOW_NAME> --workspace <TITLE> | --deployment <TITLE> [--spec '{}'] [--resume]
   flow list-runs --workspace <TITLE> | --deployment <TITLE> [--status, -f/--flow, --since, --until, --offset, --limit]
@@ -148,6 +156,13 @@ client = Client(
     instance_api_url="https://api.instance.ascend.io",
 )
 
+# Environments & Projects
+client.list_environments()
+client.get_environment(title="Production")
+client.list_projects()
+client.get_project(title="My Project")
+client.list_profiles(workspace="My Workspace")
+
 # Workspaces
 client.list_workspaces()
 client.list_workspaces(environment="Production", project="My Project")
@@ -200,6 +215,11 @@ The `mcp` subcommand starts an MCP (Model Context Protocol) server, exposing Asc
 | `pause_deployment_automations` | Pause automations on a deployment |
 | `resume_deployment_automations` | Resume automations on a deployment |
 | `delete_deployment` | Delete a deployment |
+| `list_environments` | List environments |
+| `get_environment` | Get an environment by title |
+| `list_projects` | List projects |
+| `get_project` | Get a project by title |
+| `list_profiles` | List profiles for a workspace, deployment, or project+branch |
 | `list_flows` | List flows in a workspace or deployment |
 | `run_flow` | Trigger a flow run with typed spec (resume, full_refresh, components, parameters, etc.) |
 | `list_flow_runs` | List flow runs with filters (status, flow, since, until, offset, limit) |
@@ -301,6 +321,9 @@ The SDK/CLI calls the Instance API's `/api/v1/` endpoints, defined in `ascend-ba
 | `/api/v1/runtimes/{uuid}` | GET | Get a runtime |
 | `/api/v1/runtimes/{uuid}` | PATCH | Update a runtime |
 | `/api/v1/runtimes/{uuid}` | DELETE | Delete a runtime |
+| `/api/v1/environments` | GET | List environments (filter: title) |
+| `/api/v1/projects` | GET | List projects (filter: title) |
+| `/api/v1/profiles` | GET | List profiles (filters: runtime_uuid, project, branch) |
 | `/api/v1/runtimes/{uuid}/flows` | GET | List flows in a runtime |
 | `/api/v1/runtimes/{uuid}/flows/{name}:run` | POST | Trigger a flow run |
 | `/api/v1/flow-runs` | GET | List flow runs (requires runtime_uuid, filters: status, flow, since, until) |

docs/cli.md

@@ -126,6 +126,22 @@ ascend-tools deployment resume-automations "My Deployment"
 ascend-tools deployment delete "My Deployment"
 ```
 
+## Environments, projects, and profiles
+
+```bash
+# List environments
+ascend-tools environment list
+ascend-tools environment get "Production"
+
+# List projects
+ascend-tools project list
+ascend-tools project get "My Project"
+
+# List profiles (requires a workspace/deployment or project+branch)
+ascend-tools profile list --workspace "My Workspace"
+ascend-tools profile list --project "My Project" --git-branch main
+```
+
 ## Manage flows
 
 ### List flows

docs/mcp.md

@@ -1,6 +1,6 @@
 # Set up the MCP server
 
-Connect AI assistants to Ascend using the [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server. Exposes 18 tools for managing workspaces, deployments, and flows. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and other MCP-compatible clients.
+Connect AI assistants to Ascend using the [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server. Exposes 23 tools for managing workspaces, deployments, environments, projects, profiles, and flows. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and other MCP-compatible clients.
 
 ## Remote MCP server (recommended)
 
@@ -236,6 +236,42 @@ Delete a deployment.
 |-----------|----------|------|-------------|
 | `title` | yes | string | Deployment title |
 
+### list_environments
+
+List environments. No parameters.
+
+### get_environment
+
+Get an environment by title.
+
+| Parameter | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `title` | yes | string | Environment title |
+
+### list_projects
+
+List projects. No parameters.
+
+### get_project
+
+Get a project by title.
+
+| Parameter | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `title` | yes | string | Project title |
+
+### list_profiles
+
+List available profiles for a workspace, deployment, or project+branch.
+
+| Parameter | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `workspace` | no | string | Workspace title |
+| `deployment` | no | string | Deployment title |
+| `uuid` | no | string | UUID (direct override) |
+| `project` | no | string | Project name (or UUID) — use with branch |
+| `branch` | no | string | Git branch (required with project) |
+
 ### list_flows
 
 List flows in a workspace or deployment.

docs/python.md

@@ -40,6 +40,46 @@ client = Client(
 
 All parameters are keyword-only.
 
+## Environments and projects
+
+### List environments
+
+```python
+environments = client.list_environments()
+```
+
+### Get an environment by title
+
+```python
+env = client.get_environment(title="Production")
+```
+
+Returns `dict` with the matching environment. Raises an error if not found or ambiguous.
+
+### List projects
+
+```python
+projects = client.list_projects()
+```
+
+### Get a project by title
+
+```python
+project = client.get_project(title="My Project")
+```
+
+Returns `dict` with the matching project. Raises an error if not found or ambiguous.
+
+### List profiles
+
+```python
+profiles = client.list_profiles(workspace="My Workspace")
+profiles = client.list_profiles(deployment="My Deployment")
+profiles = client.list_profiles(project="My Project", branch="main")
+```
+
+Returns `list[str]` of profile names. Provide exactly one of workspace/deployment/uuid, or project+branch.
+
 ## Manage workspaces and deployments
 
 ### Workspaces

src/ascend_tools/ascend-tools-cli/src/cli.rs

@@ -6,7 +6,10 @@ use std::ffi::OsString;
 
 use crate::common::OutputMode;
 use crate::deployment::DeploymentCommands;
+use crate::environment::EnvironmentCommands;
 use crate::flow::FlowCommands;
+use crate::profile::ProfileCommands;
+use crate::project::ProjectCommands;
 use crate::skill::SkillCommands;
 use crate::workspace::WorkspaceCommands;
 
@@ -79,6 +82,33 @@ enum Commands {
         #[command(subcommand)]
         command: Option<FlowCommands>,
     },
+    /// Manage environments
+    #[command(long_about = "Manage Ascend environments.\n\n\
+            Examples:\n  \
+            ascend-tools environment list\n  \
+            ascend-tools environment get Production")]
+    Environment {
+        #[command(subcommand)]
+        command: Option<EnvironmentCommands>,
+    },
+    /// Manage projects
+    #[command(long_about = "Manage Ascend projects.\n\n\
+            Examples:\n  \
+            ascend-tools project list\n  \
+            ascend-tools project get \"My Project\"")]
+    Project {
+        #[command(subcommand)]
+        command: Option<ProjectCommands>,
+    },
+    /// Manage profiles
+    #[command(long_about = "Manage Ascend profiles.\n\n\
+            Examples:\n  \
+            ascend-tools profile list --workspace my-ws\n  \
+            ascend-tools profile list --project MyProject --git-branch main")]
+    Profile {
+        #[command(subcommand)]
+        command: Option<ProfileCommands>,
+    },
     /// Start an MCP server
     Mcp {
         /// Use HTTP transport instead of stdio
@@ -141,6 +171,15 @@ where
         Commands::Deployment { command } => {
             crate::deployment::handle_deployment(&client, command, &cli.output)
         }
+        Commands::Environment { command } => {
+            crate::environment::handle_environment(&client, command, &cli.output)
+        }
+        Commands::Project { command } => {
+            crate::project::handle_project(&client, command, &cli.output)
+        }
+        Commands::Profile { command } => {
+            crate::profile::handle_profile(&client, command, &cli.output)
+        }
         Commands::Flow { command } => crate::flow::handle_flow(&client, command, &cli.output),
         Commands::Mcp { .. } | Commands::Skill { .. } => unreachable!(),
     }
@@ -509,4 +548,81 @@ mod tests {
             Some(Commands::Mcp { http: true, .. })
         ));
     }
+
+    #[test]
+    fn test_cli_parses_environment_list() {
+        let cli = CliParser::parse_from(["ascend-tools", "environment", "list"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Environment {
+                command: Some(EnvironmentCommands::List)
+            })
+        ));
+    }
+
+    #[test]
+    fn test_cli_parses_environment_bare_is_none() {
+        let cli = CliParser::parse_from(["ascend-tools", "environment"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Environment { command: None })
+        ));
+    }
+
+    #[test]
+    fn test_cli_parses_project_list() {
+        let cli = CliParser::parse_from(["ascend-tools", "project", "list"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Project {
+                command: Some(ProjectCommands::List)
+            })
+        ));
+    }
+
+    #[test]
+    fn test_cli_parses_profile_list_with_workspace() {
+        let cli = CliParser::parse_from(["ascend-tools", "profile", "list", "--workspace", "Cody"]);
+        match cli.command {
+            Some(Commands::Profile {
+                command:
+                    Some(ProfileCommands::List {
+                        workspace,
+                        deployment,
+                        project,
+                        ..
+                    }),
+            }) => {
+                assert_eq!(workspace.as_deref(), Some("Cody"));
+                assert!(deployment.is_none());
+                assert!(project.is_none());
+            }
+            _ => panic!("expected Profile List command"),
+        }
+    }
+
+    #[test]
+    fn test_cli_parses_profile_list_with_project_and_branch() {
+        let cli = CliParser::parse_from([
+            "ascend-tools",
+            "profile",
+            "list",
+            "--project",
+            "MyProject",
+            "--git-branch",
+            "main",
+        ]);
+        match cli.command {
+            Some(Commands::Profile {
+                command:
+                    Some(ProfileCommands::List {
+                        project, branch, ..
+                    }),
+            }) => {
+                assert_eq!(project.as_deref(), Some("MyProject"));
+                assert_eq!(branch.as_deref(), Some("main"));
+            }
+            _ => panic!("expected Profile List command"),
+        }
+    }
 }

src/ascend_tools/ascend-tools-cli/src/environment.rs

@@ -0,0 +1,55 @@
+use anyhow::Result;
+use ascend_tools::client::AscendClient;
+use clap::Subcommand;
+
+use crate::common::{OutputMode, print_json, print_subcommand_help, print_table};
+
+#[derive(Subcommand)]
+pub(crate) enum EnvironmentCommands {
+    /// List environments
+    List,
+    /// Get an environment by title
+    #[command(arg_required_else_help = true)]
+    Get {
+        /// Environment title
+        title: String,
+    },
+}
+
+pub(crate) fn handle_environment(
+    client: &AscendClient,
+    cmd: Option<EnvironmentCommands>,
+    output: &OutputMode,
+) -> Result<()> {
+    let Some(cmd) = cmd else {
+        return print_subcommand_help("environment");
+    };
+    match cmd {
+        EnvironmentCommands::List => {
+            let envs = client.list_environments()?;
+            match output {
+                OutputMode::Json => print_json(&envs)?,
+                OutputMode::Text => {
+                    let rows: Vec<Vec<String>> = envs
+                        .iter()
+                        .map(|e| vec![e.title.clone(), e.uuid.clone()])
+                        .collect();
+                    print_table(&["TITLE", "UUID"], &rows);
+                }
+            }
+            Ok(())
+        }
+        EnvironmentCommands::Get { title } => {
+            let env = client.get_environment(&title)?;
+            match output {
+                OutputMode::Json => print_json(&env)?,
+                OutputMode::Text => {
+                    println!("Title:  {}", env.title);
+                    println!("UUID:   {}", env.uuid);
+                    println!("ID:     {}", env.id);
+                }
+            }
+            Ok(())
+        }
+    }
+}

src/ascend_tools/ascend-tools-cli/src/lib.rs

@@ -3,7 +3,10 @@
 mod cli;
 mod common;
 mod deployment;
+mod environment;
 mod flow;
+mod profile;
+mod project;
 mod skill;
 mod workspace;